# suryadeepkoduri/openshop architecture

> Architecture diagram of the GitHub repository suryadeepkoduri/openshop, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/suryadeepkoduri/openshop
- Repository: https://github.com/suryadeepkoduri/openshop

## Overview

##### Project Type and Purpose
- This is a single‐service, RESTful e-commerce backend API built with Spring Boot.
- Responsibilities: user authentication (JWT), product/category management, cart & order handling, admin endpoints, enhanced request logging via MDC.

##### High-Level Components
A. API Layer (Controllers)
- Exposes REST endpoints grouped by domain:
- Public: ProductController, CategoryController, CartController, OrderController, UserController
- Admin: AdminProductController, AdminCategoryController, AdminOrderController
- Auth: AuthController
- GlobalExceptionHandler sits alongside to catch and normalize errors.
B. Service Layer
- Business logic interfaces (e.g., ProductService, OrderService) and their implementations (ProductServiceImpl, etc.).
- AuthenticationService, JwtService for token management.
C. Data Layer
- Spring Data JPA repositories (ProductRepository, OrderRepository, etc.).
- Entities mapping to MySQL tables: Product, Category, Cart, Order, User, etc.
D. Cross-Cutting Concerns
- Security: SecurityConfig defines HTTP/SecurityFilterChain, JwtAuthenticationFilter enforces JWT.
- Configuration: ApplicationConfiguration, DataSeeder (initial data load), OpenApiConfig (Swagger).
- Logging: MdcFilter and MdcUtil integrate SLF4J/Logback’s MDC context.
- DTO/Mapping: Request/Response DTOs and MapStruct mappers (OrderMapper, EntityMapper).

##### External Systems
- MySQL database (primary persistence).
- Swagger UI (API documentation endpoint).
- Clients: Web/Mobile front end or third-party integrators calling the HTTP API.

##### Relationships and Data Flows
1. Client → HTTP Request → Spring Filter Chain (MDC filter → JWT filter)
2. Filter Chain → Controller → Service → Repository → MySQL
3. Repository returns Entities → Service applies business rules → Mapper transforms to DTO → Controller returns JSON
4. Swagger UI serves OpenAPI docs from OpenApiConfig
5. DataSeeder (on startup) populates baseline data into MySQL

##### Architectural Patterns & Principles
- Layered (AKA “Onion” or “Hexagonal”) architecture: clear separation between API, business logic, and persistence.
- Dependency inversion: controllers depend on service interfaces, services depend on repositories via Spring DI.
- Single Responsibility: each package (config, controller, service, repository, entity, dto, mapper, filter, security) has well-defined concerns.
- Cross-cutting handled through filters and global exception handlers.

##### Technologies & Frameworks to Annotate
- Spring Boot (core framework)
- Spring Security with JWT
- Spring Data JPA (ORM)
- MapStruct (DTO ↔ Entity mapping)
- Lombok (boilerplate reduction)
- Swagger/OpenAPI
- SLF4J/Logback + MDC
- MySQL

##### Final Checklist
- [ ] Components: Client, Filters/Security, Controllers, Services, Repositories, MySQL, Swagger UI

## Diagram (Mermaid)

```mermaid
flowchart TD
  Client["Client"]:::external
  subgraph "OpenShop Spring Boot Monolith"
    subgraph "Filters & Security"
      MDC["MdcFilter"]:::cross
      JWTF["JwtAuthenticationFilter"]:::cross
      SC["SecurityConfig"]:::cross
      MDC --> JWTF
    end

    subgraph "Controllers"
      PC["ProductController"]:::layer
      CC["CategoryController"]:::layer
      CartC["CartController"]:::layer
      OC["OrderController"]:::layer
      UCtl["UserController"]:::layer
      APC["AdminProductController"]:::layer
      ACC["AdminCategoryController"]:::layer
      AOC["AdminOrderController"]:::layer
      AuthC["AuthController"]:::layer
      GEX["GlobalExceptionHandler"]:::layer
    end

    subgraph "Services"
      PSvc["ProductService"]:::layer
      CSvc["CategoryService"]:::layer
      CartSvc["CartService"]:::layer
      OSvc["OrderService"]:::layer
      USvc["UserService"]:::layer
      AuthSvc["AuthenticationService"]:::layer
      JwtSvc["JwtService"]:::layer
    end

    subgraph "Repositories"
      PR["ProductRepository"]:::layer
      CatR["CategoryRepository"]:::layer
      CartR["CartRepository"]:::layer
      CartItemR["CartItemRepository"]:::layer
      OrdR["OrderRepository"]:::layer
      OrdItemR["OrderItemRepository"]:::layer
      UR["UserRepository"]:::layer
      AddrR["AddressRepository"]:::layer
      VarR["VariantRepository"]:::layer
      RoleR["RoleRepository"]:::layer
    end

    subgraph "DTOs & Mappers"
      ReqDTO["Request DTOs"]:::layer
      ResDTO["Response DTOs"]:::layer
      EM["EntityMapper"]:::layer
      OM["OrderMapper"]:::layer
    end

    subgraph "Config & Startup"
      AppConf["ApplicationConfiguration"]:::layer
      OAS["OpenApiConfig"]:::layer
      DS["DataSeeder"]:::layer
    end
  end

  MySQL[(MySQL Database)]:::db
  Swagger["Swagger UI"]:::doc

  Client -->|HTTP Request| MDC
  JWTF -->|Bearer Token| PC
  GEX -->|handles errors| Client
  PC -->|calls| PSvc
  CC -->|calls| CSvc
  CartC -->|calls| CartSvc
  OC -->|calls| OSvc
  UCtl -->|calls| USvc
  APC -->|calls| PSvc
  ACC -->|calls| CSvc
  AOC -->|calls| OSvc
  AuthC -->|issues JWT| AuthSvc

  PSvc -->|uses JPA| PR
  PSvc -->|uses JPA| CatR
  CartSvc -->|uses JPA| CartR
  OSvc -->|uses JPA| OrdR
  USvc -->|uses JPA| UR
  AuthSvc -->|uses JwtService| JwtSvc

  PR -->|reads/writes| MySQL
  CatR -->|reads/writes| MySQL
  CartR -->|reads/writes| MySQL
  OrdR -->|reads/writes| MySQL
  UR -->|reads/writes| MySQL

  DS -->|initial load| MySQL
  OAS -->|serves API docs| Swagger

  classDef layer fill:#D0E6FF,stroke:#0366D6,stroke-width:1px
  classDef cross fill:none,stroke:#FF8C00,stroke-dasharray: 5 5,stroke-width:1px
  classDef external fill:#E2F0D9,stroke:#2E7D32,stroke-width:1px
  classDef db fill:#C8E6C9,stroke:#388E3C,stroke-width:1px,shape:cylinder
  classDef doc fill:#FFF3E0,stroke:#F57C00,stroke-width:1px

  click MDC "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/filter/MdcFilter.java"
  click JWTF "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/security/JwtAuthenticationFilter.java"
  click SC "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/config/SecurityConfig.java"
  click PC "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/controller/ProductController.java"
  click CC "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/controller/CategoryController.java"
  click CartC "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/controller/CartController.java"
  click OC "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/controller/OrderController.java"
  click UCtl "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/controller/UserController.java"
  click APC "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/controller/admin/AdminProductController.java"
  click ACC "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/controller/admin/AdminCategoryController.java"
  click AOC "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/controller/admin/AdminOrderController.java"
  click AuthC "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/controller/authentication/AuthController.java"
  click GEX "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/controller/GlobalExceptionHandler.java"
  click PSvc "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/service/ProductService.java"
  click CSvc "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/service/CategoryService.java"
  click CartSvc "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/service/CartService.java"
  click OSvc "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/service/OrderService.java"
  click USvc "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/service/UserService.java"
  click AuthSvc "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/service/AuthenticationService.java"
  click JwtSvc "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/service/JwtService.java"
  click PR "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/repository/ProductRepository.java"
  click CatR "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/repository/CategoryRepository.java"
  click CartR "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/repository/CartRepository.java"
  click CartItemR "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/repository/CartItemRepository.java"
  click OrdR "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/repository/OrderRepository.java"
  click OrdItemR "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/repository/OrderItemRepository.java"
  click UR "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/repository/UserRepository.java"
  click AddrR "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/repository/AddressRepository.java"
  click VarR "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/repository/VariantRepository.java"
  click RoleR "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/repository/RoleRepository.java"
  click EM "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/mapper/EntityMapper.java"
  click OM "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/mapper/OrderMapper.java"
  click AppConf "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/config/ApplicationConfiguration.java"
  click OAS "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/config/OpenApiConfig.java"
  click DS "https://github.com/suryadeepkoduri/openshop/blob/main/src/main/java/com/suryadeep/openshop/config/DataSeeder.java"
```
