🛒 FazCart

A Modern Full-Stack eCommerce Platform

A feature-rich, production-ready eCommerce application built with a React + TypeScript frontend and a Java Spring Boot REST API backend.

---

📋 Table of Contents

• Overview
• Features
• Tech Stack
  • Frontend
  • Backend
  • Infrastructure
• Architecture
• Getting Started
  • Prerequisites
  • Backend Setup
  • Frontend Setup
  • Docker Setup
• API Documentation
• Project Structure

---

🌟 Overview

FazCart is a full-stack eCommerce platform designed for performance and scalability. The frontend delivers a modern, responsive shopping experience powered by React 19 and Tailwind CSS, while the backend provides a secure, rate-limited REST API built with Spring Boot, Spring Security (JWT), and PostgreSQL.

---

✨ Features

• 🔐 Authentication & Authorization — JWT-based register/login with Spring Security
• 🛍️ Product Catalog — Browse, filter, and view detailed product pages
• 🛒 Shopping Cart — Add, update, and remove items in real time
• 📦 Order Management — Checkout flow and full order history tracking
• 👤 User Profile — View and manage account details
• 🌙 Dark / Light Mode — System-aware theme switching
• 🚦 Rate Limiting — Bucket4j-powered API throttling to prevent abuse
• 📄 API Docs — Interactive Swagger UI via SpringDoc OpenAPI
• 🐳 Docker Ready — Multi-stage Dockerfile for clean, optimized backend images

---

🧰 Tech Stack

🖥️ Frontend

Technology	Purpose
	Core UI framework
	Static typing
	Build tool & dev server
	Utility-first styling
	Accessible component library
	Headless UI primitives
	Global state management
	Server state & data fetching
	Client-side routing
	HTTP client
	Animations & transitions
	3D background graphics
	Lightweight local state
	Toast notifications
	Dark/light mode
	Icon library

⚙️ Backend

Technology	Purpose
	Core language
	Application framework
	Authentication & authorization
	ORM & database access layer
	Relational database
	Stateless authentication tokens
	API rate limiting
	Swagger UI documentation
	Boilerplate code reduction
	Build & dependency management

🐳 Infrastructure

Technology	Purpose
	Backend containerization (multi-stage build)

---

🏗️ Architecture

FazCart-eCommerce/
├── frontend/          # React + TypeScript SPA (Vite)
│   └── src/
│       ├── app/       # Redux store, Axios instance, theme config
│       ├── components/# Shared visual components (3D, animations)
│       ├── features/  # Feature modules (auth, cart, orders, products, user)
│       ├── pages/     # Route-level page components
│       ├── routes/    # App routing configuration
│       └── shared/    # Shared utilities and UI
│
└── backend/           # Spring Boot REST API
    └── src/main/java/com/faz/ecommerce/
        ├── config/    # Security & OpenAPI configuration
        ├── controller/# REST controllers (Auth, Cart, Order, Product, User)
        ├── dto/       # Request/Response data transfer objects
        ├── entity/    # JPA entities (User, Product, Cart, Order)
        ├── repository/# Spring Data JPA repositories
        ├── security/  # JWT filter, rate limiter, user details
        └── service/   # Business logic layer

---

🚀 Getting Started

Prerequisites

• Node.js v20+ & npm
• Java 17+
• Maven 3.9+
• PostgreSQL 14+
• Docker (optional)

---

Backend Setup

1. Create the PostgreSQL database:

   CREATE DATABASE ecommerce;

2. Configure credentials in backend/src/main/resources/application-dev.properties:

   spring.datasource.url=jdbc:postgresql://localhost:5432/ecommerce
   spring.datasource.username=your_username
   spring.datasource.password=your_password

3. Run the application:

   cd backend
   ./mvnw spring-boot:run

   The API will be available at http://localhost:8080.

---

Frontend Setup

1. Install dependencies:

   cd frontend
   npm install

2. Start the development server:

   npm run dev

   The app will be available at http://localhost:5173.

---

Docker Setup

Build and run the backend in a Docker container:

cd backend
docker build -t fazcart-backend .
docker run -p 8080:8080 \
  -e SPRING_DATASOURCE_URL=jdbc:postgresql://host.docker.internal:5432/ecommerce \
  -e SPRING_DATASOURCE_USERNAME=your_username \
  -e SPRING_DATASOURCE_PASSWORD=your_password \
  fazcart-backend

---

📄 API Documentation

Once the backend is running, interactive API docs are available at:

http://localhost:8080/swagger-ui.html

Key Endpoints

Method	Endpoint	Description
POST	/api/auth/register	Register a new user
POST	/api/auth/login	Login and receive JWT
GET	/api/products	List all products
GET	/api/products/{id}	Get product details
GET	/api/cart	Get current user's cart
POST	/api/cart	Add item to cart
DELETE	/api/cart/{id}	Remove item from cart
POST	/api/orders	Place an order (checkout)
GET	/api/orders	Get order history
GET	/api/user/profile	Get user profile

---

📁 Project Structure

Frontend

frontend/src/
├── app/
│   ├── store.ts          # Redux store configuration
│   ├── hooks.ts          # Typed Redux hooks
│   ├── axios.ts          # Axios instance with JWT interceptor
│   └── theme/            # Theme tokens and config
├── components/
│   ├── FloatingLines.tsx  # Animated background (Three.js / OGL)
│   └── ShapeGrid.tsx      # Decorative grid component
├── features/
│   ├── auth/             # Login, register, auth state (Redux slice)
│   ├── cart/             # Cart management
│   ├── orders/           # Order placement and history
│   ├── products/         # Product listing & detail queries
│   └── user/             # User profile
├── pages/
│   ├── Home.tsx
│   ├── Auth.tsx
│   ├── Products.tsx
│   ├── ProductDetails.tsx
│   ├── Cart.tsx
│   ├── Checkout.tsx
│   ├── Order.tsx
│   └── UserProfile.tsx
└── routes/
    └── AppRoutes.tsx     # React Router configuration

Backend

backend/src/main/java/com/faz/ecommerce/
├── config/
│   ├── SecurityConfig.java    # Spring Security & CORS config
│   └── OpenApiConfig.java     # Swagger / OpenAPI config
├── controller/
│   ├── AuthController.java
│   ├── CartController.java
│   ├── OrderController.java
│   ├── ProductController.java
│   └── UserController.java
├── dto/                       # Request & Response DTOs
├── entity/
│   ├── User.java
│   ├── Product.java
│   ├── CartItem.java
│   ├── Order.java
│   └── OrderItem.java
├── enums/
│   └── OrderStatus.java
├── exception/
│   ├── GlobalExceptionHandler.java
│   ├── BadRequestException.java
│   └── UnauthorizedException.java
├── repository/                # Spring Data JPA repositories
├── security/
│   ├── JwtUtil.java
│   ├── JwtAuthenticationFilter.java
│   ├── RateLimitFilter.java   # Bucket4j rate limiting
│   └── CustomUserDetails.java
└── service/                   # Business logic

---

Made with ❤️ by Faz