# prantascode/ecommerce-website architecture

> Architecture diagram of the GitHub repository prantascode/ecommerce-website, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/prantascode/ecommerce-website
- Repository: https://github.com/prantascode/ecommerce-website

## Overview

1. This repository is a Spring Boot backend for an e-commerce system, not a full frontend app. The architectural center is a REST API that exposes business capabilities for authentication, catalog management, cart, orders, payments, reviews, wishlists, and admin/customer operations.

2. The codebase follows a clear layered structure: `Controller` handles HTTP endpoints, `Service` contains business rules, `Repository` provides persistence access, and `Entity` defines the database model. This is the main boundary an architecture diagram should show, with requests flowing downward and DTOs used at the API edge.

3. Authentication and authorization are a major subsystem. `AuthController`, `AuthService`, `CustomUserDetailsService`, `JwtFilter`, `Jwtutil`, and `SecurityConfig` work together to handle registration, login, JWT issuance/validation, refresh tokens, and role-based access control for `ADMIN` and `CUSTOMER`.

4. Domain data is modeled with JPA entities for `User`, `Customer`, `Product`, `Brand`, `Category`, `Cart`, `CartItem`, `Order`, `OrderItem`, `Payment`, `Review`, `Wishlist`, `Discount`, and `RefreshToken`. These entities are persisted through Spring Data repositories and represent the core business state in MySQL.

5. Product and catalog management are isolated into their own flow: `ProductController` and `ProductService` manage products, while `BrandController`/`BrandService` and `CategoryController`/`CategoryService` support classification and filtering. `DiscountController`/`DiscountService` adds pricing logic that likely affects product and order calculations.

6. Cart and checkout form another business pipeline. `CartController` and `CartService` manage cart state and cart items, then `OrderController` and `OrderService` convert cart contents into orders and order items. This is the key transactional handoff from shopping to purchase.

7. Payment integration is a separate boundary around external processing. `PaymentController`, `PaymentService`, and `SSLCommerzConfig` indicate integration with the SSLCommerz gateway for payment initiation and verification, with `Payment` persisted as an internal record of the transaction outcome.

8. Reviews and wishlists are auxiliary customer-facing features. `ReviewController`/`ReviewService` manage product feedback, and `WishlistController`/`WishlistService` handle saved items. These are independent from the core checkout path but still tied to authenticated users and products.

9. The API surface is strongly typed with request/response DTOs under `Dto/Request` and `Dto/Response`. This keeps controllers decoupled from persistence entities and makes the external contract explicit for login, registration, product updates, order placement, payment responses, and similar operations.

10. Error handling is centralized. Custom exceptions such as `ResourceNotFoundException`, `DuplicateResourceException`, `InvalidRequestException`, and `UnauthorizedAccessException` are translated by `GlobalExceptionHandler` into a structured `ErrorResponseDto`, which is an important cross-cutting boundary for API reliability.

11. The application includes operational support components: `OpenApiConfig` for Swagger/OpenAPI documentation, `DataInitializer` for bootstrapping data, and `CartCleanupScheduler` for periodic cart maintenance. These are supporting subsystems rather than primary business flows, but they affect runtime behavior.

12. Persistence and runtime environment are straightforward: the project uses Maven, Spring Boot, Spring Security, Spring Data JPA/Hibernate, and MySQL, with configuration driven from `application.properties`. There is a single backend deployable (`EcommerceApplication`) and a basic test entry point under `src/test`.

Main entry points: [`src/main/java/com/pranta/ecommerce/EcommerceApplication.java`](https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/EcommerceApplication.java) (App), [`src/main/java/com/pranta/ecommerce/Dto`](https://github.com/prantascode/ecommerce-website/tree/main/src/main/java/com/pranta/ecommerce/Dto) (DTOs), [`src/main/java/com/pranta/ecommerce/Repository`](https://github.com/prantascode/ecommerce-website/tree/main/src/main/java/com/pranta/ecommerce/Repository) (Repositories), [`src/main/java/com/pranta/ecommerce/Controller/AuthController.java`](https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/Controller/AuthController.java) (Auth API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_api["API Layer"]
  node_auth_ctrl["Auth API<br/>controller"]
  node_catalog_ctrl["Catalog API<br/>controllers"]
  node_cart_ctrl["Cart API<br/>controller"]
  node_order_ctrl["Order API<br/>controller"]
  node_payment_ctrl["Payment API<br/>controller"]
  node_social_ctrl["Social API<br/>controllers"]
  node_user_ctrl["User API<br/>controller"]
  node_dto["DTOs<br/>api contracts"]
end

subgraph group_grp_domain["Domain Layer"]
  node_auth_svc["Auth Service<br/>[AuthService.java]"]
  node_catalog_svc["Catalog Service"]
  node_cart_order_svc["Checkout Flow<br/>services<br/>[CartService.java]"]
  node_payment_svc["Payment Service"]
  node_social_svc["Customer Features<br/>services<br/>[ReviewService.java]"]
end

subgraph group_grp_data["Data Layer"]
  node_entities[("Entities<br/>jpa models")]
  node_repos["Repositories<br/>spring data"]
end

subgraph group_grp_cross["Cross-cutting"]
  node_app(("App<br/>Spring Boot entrypoint"))
  node_security["Security<br/>[JwtFilter.java]"]
  node_config["Config"]
  node_errors["Errors<br/>exception handling"]
  node_scheduler["Scheduler<br/>background job"]
end

node_app -->|"serves"| node_auth_ctrl
node_app -->|"serves"| node_catalog_ctrl
node_app -->|"serves"| node_cart_ctrl
node_app -->|"serves"| node_order_ctrl
node_app -->|"serves"| node_payment_ctrl
node_app -->|"serves"| node_social_ctrl
node_app -->|"serves"| node_user_ctrl
node_auth_ctrl -->|"calls"| node_auth_svc
node_catalog_ctrl -->|"calls"| node_catalog_svc
node_cart_ctrl -->|"calls"| node_cart_order_svc
node_order_ctrl -->|"calls"| node_cart_order_svc
node_payment_ctrl -->|"calls"| node_payment_svc
node_social_ctrl -->|"calls"| node_social_svc
node_user_ctrl -->|"calls"| node_social_svc
node_auth_svc -->|"uses"| node_security
node_auth_svc -->|"persists"| node_repos
node_catalog_svc -->|"persists"| node_repos
node_cart_order_svc -->|"persists"| node_repos
node_payment_svc -->|"uses"| node_config
node_payment_svc -->|"persists"| node_repos
node_social_svc -->|"persists"| node_repos
node_security -->|"configured by"| node_config
node_repos -->|"maps"| node_entities
node_dto -.->|"contracts"| node_auth_ctrl
node_dto -.->|"contracts"| node_catalog_ctrl
node_dto -.->|"contracts"| node_cart_ctrl
node_dto -.->|"contracts"| node_order_ctrl
node_dto -.->|"contracts"| node_payment_ctrl
node_dto -.->|"contracts"| node_social_ctrl
node_errors -.->|"handles"| node_auth_ctrl
node_errors -.->|"handles"| node_catalog_ctrl
node_errors -.->|"handles"| node_cart_ctrl
node_scheduler -.->|"triggers"| node_cart_order_svc

click node_app "https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/EcommerceApplication.java"
click node_auth_ctrl "https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/Controller/AuthController.java"
click node_catalog_ctrl "https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/Controller/ProductController.java"
click node_cart_ctrl "https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/Controller/CartController.java"
click node_order_ctrl "https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/Controller/OrderController.java"
click node_payment_ctrl "https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/Controller/PaymentController.java"
click node_social_ctrl "https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/Controller/ReviewController.java"
click node_user_ctrl "https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/Controller/UserController.java"
click node_dto "https://github.com/prantascode/ecommerce-website/tree/main/src/main/java/com/pranta/ecommerce/Dto"
click node_auth_svc "https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/Service/AuthService.java"
click node_catalog_svc "https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/Service/ProductService.java"
click node_cart_order_svc "https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/Service/CartService.java"
click node_payment_svc "https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/Service/PaymentService.java"
click node_social_svc "https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/Service/ReviewService.java"
click node_security "https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/Security/JwtFilter.java"
click node_config "https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/Config/SecurityConfig.java"
click node_errors "https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/Exceptions/GlobalExceptionHandler.java"
click node_scheduler "https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/Scheduler/CartCleanupScheduler.java"
click node_entities "https://github.com/prantascode/ecommerce-website/tree/main/src/main/java/com/pranta/ecommerce/Entity"
click node_repos "https://github.com/prantascode/ecommerce-website/tree/main/src/main/java/com/pranta/ecommerce/Repository"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_auth_ctrl,node_catalog_ctrl,node_cart_ctrl,node_order_ctrl,node_payment_ctrl,node_social_ctrl,node_user_ctrl,node_dto toneBlue
class node_auth_svc,node_catalog_svc,node_cart_order_svc,node_payment_svc,node_social_svc toneAmber
class node_entities,node_repos toneMint
class node_app,node_security,node_config,node_errors,node_scheduler toneRose
```

## Components

### API Layer

HTTP controllers and DTOs at the application boundary

- [Auth API](https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/Controller/AuthController.java): controller · Login, registration, token refresh, and auth endpoints · `src/main/java/com/pranta/ecommerce/Controller/AuthController.java`
- [Catalog API](https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/Controller/ProductController.java): controllers · Product, brand, category, and discount endpoints · `src/main/java/com/pranta/ecommerce/Controller/ProductController.java`
- [Cart API](https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/Controller/CartController.java): controller · Cart and cart item endpoints · `src/main/java/com/pranta/ecommerce/Controller/CartController.java`
- [Order API](https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/Controller/OrderController.java): controller · Order placement and order update endpoints · `src/main/java/com/pranta/ecommerce/Controller/OrderController.java`
- [Payment API](https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/Controller/PaymentController.java): controller · Payment initiation and verification endpoints · `src/main/java/com/pranta/ecommerce/Controller/PaymentController.java`
- [Social API](https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/Controller/ReviewController.java): controllers · Review and wishlist endpoints · `src/main/java/com/pranta/ecommerce/Controller/ReviewController.java`
- [User API](https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/Controller/UserController.java): controller · Customer and user administration endpoints · `src/main/java/com/pranta/ecommerce/Controller/UserController.java`
- [DTOs](https://github.com/prantascode/ecommerce-website/tree/main/src/main/java/com/pranta/ecommerce/Dto): api contracts · Request and response models for the REST API · `src/main/java/com/pranta/ecommerce/Dto`

### Domain Layer

Business services and core workflows

- [Auth Service](https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/Service/AuthService.java): service · Authentication, JWT, and refresh token flows · `src/main/java/com/pranta/ecommerce/Service/AuthService.java`
- [Catalog Service](https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/Service/ProductService.java): service · Products, brands, categories, and discount rules · `src/main/java/com/pranta/ecommerce/Service/ProductService.java`
- [Checkout Flow](https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/Service/CartService.java): services · Cart handling, order creation, and order items · `src/main/java/com/pranta/ecommerce/Service/CartService.java`
- [Payment Service](https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/Service/PaymentService.java): service · Gateway integration and payment record handling · `src/main/java/com/pranta/ecommerce/Service/PaymentService.java`
- [Customer Features](https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/Service/ReviewService.java): services · Reviews, wishlists, and customer-facing account actions · `src/main/java/com/pranta/ecommerce/Service/ReviewService.java`

### Data Layer

Entities and repositories for persistence

- [Entities](https://github.com/prantascode/ecommerce-website/tree/main/src/main/java/com/pranta/ecommerce/Entity): jpa models · User, product, order, payment, review, wishlist, and token state · `src/main/java/com/pranta/ecommerce/Entity`
- [Repositories](https://github.com/prantascode/ecommerce-website/tree/main/src/main/java/com/pranta/ecommerce/Repository): spring data · Persistence access for core domain aggregates · `src/main/java/com/pranta/ecommerce/Repository`

### Cross-cutting

Security, configuration, errors, and runtime support

- [App](https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/EcommerceApplication.java): Spring Boot entrypoint · Application bootstrap and runtime entry · `src/main/java/com/pranta/ecommerce/EcommerceApplication.java`
- [Security](https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/Security/JwtFilter.java): security config · JWT filter, user details, and access rules · `src/main/java/com/pranta/ecommerce/Security/JwtFilter.java`
- [Config](https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/Config/SecurityConfig.java): spring config · Security, OpenAPI, and payment gateway configuration · `src/main/java/com/pranta/ecommerce/Config/SecurityConfig.java`
- [Errors](https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/Exceptions/GlobalExceptionHandler.java): exception handling · Custom exceptions and global API error mapping · `src/main/java/com/pranta/ecommerce/Exceptions/GlobalExceptionHandler.java`
- [Scheduler](https://github.com/prantascode/ecommerce-website/blob/main/src/main/java/com/pranta/ecommerce/Scheduler/CartCleanupScheduler.java): background job · Periodic cart cleanup task · `src/main/java/com/pranta/ecommerce/Scheduler/CartCleanupScheduler.java`

## Connections

- App → Auth API: serves · Bootstraps REST authentication endpoints
- App → Catalog API: serves · Bootstraps catalog endpoints
- App → Cart API: serves · Bootstraps cart endpoints
- App → Order API: serves · Bootstraps order endpoints
- App → Payment API: serves · Bootstraps payment endpoints
- App → Social API: serves · Bootstraps review and wishlist endpoints
- App → User API: serves · Bootstraps user and customer endpoints
- Auth API → Auth Service: calls · Delegates authentication and token operations
- Catalog API → Catalog Service: calls · Delegates catalog and pricing rules
- Cart API → Checkout Flow: calls · Delegates cart state changes
- Order API → Checkout Flow: calls · Delegates order creation and updates
- Payment API → Payment Service: calls · Delegates gateway operations
- Social API → Customer Features: calls · Delegates review and wishlist actions
- User API → Customer Features: calls · Delegates customer and profile operations
- Auth Service → Security: uses · JWT validation and user lookup
- Auth Service → Repositories: persists · Reads and writes users and refresh tokens
- Catalog Service → Repositories: persists · Uses product, brand, category, and discount repositories
- Checkout Flow → Repositories: persists · Uses cart, order, and order item repositories
- Payment Service → Config: uses · Uses payment gateway configuration
- Payment Service → Repositories: persists · Stores payment outcomes
- Customer Features → Repositories: persists · Uses review and wishlist repositories
- Security → Config: configured by · Security chain and JWT settings
- Repositories → Entities: maps · Spring Data repositories operate on JPA entities
- DTOs → Auth API: contracts · Request and response models at the API boundary
- DTOs → Catalog API: contracts · Typed catalog requests and responses
- DTOs → Cart API: contracts · Typed cart requests and responses
- DTOs → Order API: contracts · Typed order requests and responses
- DTOs → Payment API: contracts · Typed payment responses
- DTOs → Social API: contracts · Typed review and wishlist payloads
- Errors → Auth API: handles · Translates controller and service failures
- Errors → Catalog API: handles · Translates controller and service failures
- Errors → Cart API: handles · Translates controller and service failures
- Scheduler → Checkout Flow: triggers · Runs periodic cart cleanup through cart logic