# eddyy1410/gundam-sale-app architecture

> Architecture diagram of the GitHub repository eddyy1410/gundam-sale-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eddyy1410/gundam-sale-app
- Repository: https://github.com/eddyy1410/gundam-sale-app

## Overview

##### Project type and purpose
- This is a Spring Boot monolithic backend API for a mobile “Gundam Shop” e-commerce app.
- It exposes RESTful endpoints for user authentication, product catalog, shopping cart, orders, notifications, store location and real-time chat.
- It follows a Layered Architecture (Presentation, Business, Data Access, Domain, plus cross-cutting concerns like security and configuration).

##### File structure
- Top-level build files (pom.xml, mvnw) and a README.md.
- src/main/java/com/huyntd/superapp/gundam_shop/ contains:
- configuration/ – Spring, security, OpenAPI, Google token verifier
- controller/ – REST controllers by resource (Authentication, User, Category, Product)
- dto/ – request/response objects for each endpoint
- exception/ – AppException, ErrorCode, GlobalExceptionHandler
- mapper/ – MapStruct-style mappers between DTOs and Entities
- model/ – JPA Entities (User, Product, Category, Order, CartItem, Conversation, Message, Notification, etc.) and enums
- repository/ – Spring Data JPA repositories per aggregate
- service/ – Business logic interfaces and implementations (AuthenticationService, UserService, CategoryService, ProductService)
- src/main/resources/application.properties for DB connection
- src/test for unit/integration tests
- uploads/ directory for file storage (product images, etc.)

##### README for further insights
- Confirms use of Spring MVC, Spring Data JPA, Spring Security (JWT), Swagger/OpenAPI
- Database: MySQL or SQL Server, auto-generated tables via Hibernate
- Features: registration/login, product listing, details, cart, billing, notifications, map, chat

a. Main components
- Client: Mobile App (iOS/Android)
- API Server (monolith) subdivided into:
- Presentation Layer: Controllers + Swagger UI
- Business Layer: Service interfaces & implementations
- Data Access Layer: Repositories
- Domain Layer: JPA Entities (models)
- DTO/Mapper Layer: DTOs and mappers
- Configuration & Security: JWT filter, OAuth2 token verifier, CORS, etc.
- Exception Handling: GlobalExceptionHandler
- Database: MySQL (tables for Users, Products, Orders, CartItems, Conversations, Messages, Notifications…)
- External Services:
- OAuth2 Provider (Google)
- Payment Gateways (VNPay, ZaloPay, PayPal)
- /Geo API for store locations
- Real-time Chat Engine (WebSocket server or Firebase)
- File Storage (uploads folder or cloud storage)

b. Relationships and data flow
- Client → HTTP(S) → Controller
- Controller → Service → Repository → Database
- Service uses Mapper to convert between DTOs and Entities
- SecurityConfig applies JWT filter before controllers
- Swagger UI sits alongside controllers under /swagger-ui.html
- For chat, Client ↔ WebSocket/Firebase (bypass standard REST flow)
- Payment flows: Client → API → External Payment Gateway → API → Database

c. Architectural patterns & design principles
- Layered Architecture for separation of concerns
- Dependency Injection for loose coupling
- DTO pattern for API contracts
- Centralized exception handling (@ControllerAdvice)
- Security as a cross-cutting concern (JWT, OAuth2)
- Use of standard Spring Boot auto-configuration

d. Key technologies/frameworks
- Spring Boot, Spring MVC (REST controllers)
- Spring Security (JWT), Google OAuth2
- Spring Data JPA, Hibernate, MySQL
- Swagger/OpenAPI 3
- Maven build
- Java 17+

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    MobileApp["Mobile App (iOS/Android)"]:::external
    MobileApp -->|HTTPS| SecurityFilter

    %% Security Filter
    SecurityFilter["JWT & OAuth2 Filter"]:::layer
    click SecurityFilter "https://github.com/eddyy1410/gundam-sale-app/blob/master/src/main/java/com/huyntd/superapp/gundam_shop/configuration/SecurityConfig.java"

    %% API Server
    subgraph "API Server"
        direction TB

        %% Presentation Layer
        subgraph "Presentation Layer" 
            direction TB
            AuthenticationController["AuthenticationController"]:::layer
            UserController["UserController"]:::layer
            CategoryController["CategoryController"]:::layer
            ProductController["ProductController"]:::layer
            SwaggerUI["Swagger UI (/swagger-ui.html)"]:::layer
        end

        SecurityFilter --> AuthenticationController
        SecurityFilter --> UserController
        SecurityFilter --> CategoryController
        SecurityFilter --> ProductController

        %% DTO & Mapper Layer
        subgraph "DTO & Mapper Layer"
            direction TB
            DTO["DTOs (request/response)"]:::layer
            Mapper["MapStruct Mappers"]:::layer
        end

        AuthenticationController --> DTO
        UserController --> DTO
        CategoryController --> DTO
        ProductController --> DTO

        DTO --> Mapper

        %% Business Layer
        subgraph "Business Layer"
            direction TB
            AuthenticationService["AuthenticationService"]:::layer
            UserService["UserService"]:::layer
            CategoryService["CategoryService"]:::layer
            ProductService["ProductService"]:::layer
        end

        Mapper --> AuthenticationService
        Mapper --> UserService
        Mapper --> CategoryService
        Mapper --> ProductService

        AuthenticationController --> AuthenticationService
        UserController --> UserService
        CategoryController --> CategoryService
        ProductController --> ProductService

        %% Data Access Layer
        subgraph "Data Access Layer"
            direction TB
            UserRepo["UserRepository"]:::layer
            CategoryRepo["CategoryRepository"]:::layer
            ProductRepo["ProductRepository"]:::layer
            ProductImageRepo["ProductImageRepository"]:::layer
        end

        AuthenticationService --> UserRepo
        UserService --> UserRepo
        CategoryService --> CategoryRepo
        ProductService --> ProductRepo
        ProductService --> ProductImageRepo

        %% Domain Layer
        subgraph "Domain Layer"
            direction TB
            Entities["JPA Entities & Enums"]:::layer
        end

        UserRepo --> Entities
        CategoryRepo --> Entities
        ProductRepo --> Entities
        ProductImageRepo --> Entities

        %% Configuration & Init
        subgraph "Configuration & Init"
            direction TB
            AppInit["ApplicationInitConfig"]:::layer
            OpenApi["OpenApiConfig"]:::layer
            GoogleVerifier["GoogleTokenVerifier"]:::layer
        end

        AppInit --> SecurityFilter
        AppInit --> OpenApi
        AuthenticationController --> GoogleVerifier

        %% Exception Handling
        GlobalExceptionHandler["GlobalExceptionHandler"]:::layer
        AuthenticationController --> GlobalExceptionHandler
        UserController --> GlobalExceptionHandler
        CategoryController --> GlobalExceptionHandler
        ProductController --> GlobalExceptionHandler
    end

    %% Database
    Database[(MySQL Database)]:::storage
    Entities --> Database
    ApplicationProperties["application.properties"]:::storage
    click ApplicationProperties "https://github.com/eddyy1410/gundam-sale-app/blob/master/src/main/resources/application.properties"

    %% File Storage
    Uploads["uploads/ (File Storage)"]:::storage
    ProductController --> Uploads

    %% External Services
    OAuth2["OAuth2 Provider (Google)"]:::external
    PaymentGW["Payment Gateways (VNPay, ZaloPay, PayPal)"]:::external
    MapAPI["Map/Geo API"]:::external
    ChatServer["WebSocket / Firebase Chat"]:::external

    AuthenticationService -->|OAuth2 token validation| OAuth2
    ProductService -->|Process payment| PaymentGW
    UserService -->|Store location lookup| MapAPI
    MobileApp <-->|WebSocket| ChatServer

    %% Application Entry Point
    GundamApp["GundamShopApplication"]:::layer
    GundamApp --> AppInit
    GundamApp --> AuthenticationController
    click GundamApp "https://github.com/eddyy1410/gundam-sale-app/blob/master/src/main/java/com/huyntd/superapp/gundam_shop/GundamShopApplication.java"

    %% Tests
    Tests["GundamShopApplicationTests"]:::layer
    click Tests "https://github.com/eddyy1410/gundam-sale-app/blob/master/src/test/java/com/huyntd/superapp/gundam_shop/GundamShopApplicationTests.java"

    %% Click Events for Controllers
    click AuthenticationController "https://github.com/eddyy1410/gundam-sale-app/blob/master/src/main/java/com/huyntd/superapp/gundam_shop/controller/AuthenticationController.java"
    click UserController "https://github.com/eddyy1410/gundam-sale-app/blob/master/src/main/java/com/huyntd/superapp/gundam_shop/controller/UserController.java"
    click CategoryController "https://github.com/eddyy1410/gundam-sale-app/blob/master/src/main/java/com/huyntd/superapp/gundam_shop/controller/CategoryController.java"
    click ProductController "https://github.com/eddyy1410/gundam-sale-app/blob/master/src/main/java/com/huyntd/superapp/gundam_shop/controller/ProductController.java"
    click OpenApi "https://github.com/eddyy1410/gundam-sale-app/blob/master/src/main/java/com/huyntd/superapp/gundam_shop/configuration/OpenApiConfig.java"

    %% Click Events for Services
    click AuthenticationService "https://github.com/eddyy1410/gundam-sale-app/blob/master/src/main/java/com/huyntd/superapp/gundam_shop/service/Authentication/AuthenticationService.java"
    click AuthenticationServiceImplement "https://github.com/eddyy1410/gundam-sale-app/blob/master/src/main/java/com/huyntd/superapp/gundam_shop/service/Authentication/Implementation/AuthenticationServiceImplement.java"
    click UserService "https://github.com/eddyy1410/gundam-sale-app/blob/master/src/main/java/com/huyntd/superapp/gundam_shop/service/User/UserService.java"
    click UserServiceImplement "https://github.com/eddyy1410/gundam-sale-app/blob/master/src/main/java/com/huyntd/superapp/gundam_shop/service/User/Implementation/UserServiceImplement.java"
    click CategoryService "https://github.com/eddyy1410/gundam-sale-app/blob/master/src/main/java/com/huyntd/superapp/gundam_shop/service/category/CategoryService.java"
    click CategoryServiceImpl "https://github.com/eddyy1410/gundam-sale-app/blob/master/src/main/java/com/huyntd/superapp/gundam_shop/service/category/impl/CategoryServiceImpl.java"
    click ProductService "https://github.com/eddyy1410/gundam-sale-app/blob/master/src/main/java/com/huyntd/superapp/gundam_shop/service/product/ProductService.java"
    click ProductServiceImpl "https://github.com/eddyy1410/gundam-sale-app/blob/master/src/main/java/com/huyntd/superapp/gundam_shop/service/product/impl/ProductServiceImpl.java"

    %% Click Events for Repositories
    click UserRepo "https://github.com/eddyy1410/gundam-sale-app/blob/master/src/main/java/com/huyntd/superapp/gundam_shop/repository/UserRepository.java"
    click CategoryRepo "https://github.com/eddyy1410/gundam-sale-app/blob/master/src/main/java/com/huyntd/superapp/gundam_shop/repository/CategoryRepository.java"
    click ProductRepo "https://github.com/eddyy1410/gundam-sale-app/blob/master/src/main/java/com/huyntd/superapp/gundam_shop/repository/ProductRepository.java"
    click ProductImageRepo "https://github.com/eddyy1410/gundam-sale-app/blob/master/src/main/java/com/huyntd/superapp/gundam_shop/repository/ProductImageRepository.java"

    %% Click Events for Domain
    click Entities "https://github.com/eddyy1410/gundam-sale-app/tree/master/src/main/java/com/huyntd/superapp/gundam_shop/model"

    %% Click Events for DTO & Mapper
    click DTO "https://github.com/eddyy1410/gundam-sale-app/tree/master/src/main/java/com/huyntd/superapp/gundam_shop/dto"
    click Mapper "https://github.com/eddyy1410/gundam-sale-app/tree/master/src/main/java/com/huyntd/superapp/gundam_shop/mapper"

    %% Click Events for Config & Security
    click AppInit "https://github.com/eddyy1410/gundam-sale-app/blob/master/src/main/java/com/huyntd/superapp/gundam_shop/configuration/ApplicationInitConfig.java"
    click GoogleVerifier "https://github.com/eddyy1410/gundam-sale-app/blob/master/src/main/java/com/huyntd/superapp/gundam_shop/configuration/GoogleTokenVerifier.java"

    %% Click Events for Exception
    click GlobalExceptionHandler "https://github.com/eddyy1410/gundam-sale-app/blob/master/src/main/java/com/huyntd/superapp/gundam_shop/exception/GlobalExceptionHandler.java"
    click AppException "https://github.com/eddyy1410/gundam-sale-app/blob/master/src/main/java/com/huyntd/superapp/gundam_shop/exception/AppException.java"
    click ErrorCode "https://github.com/eddyy1410/gundam-sale-app/blob/master/src/main/java/com/huyntd/superapp/gundam_shop/exception/ErrorCode.java"

    %% Click for Uploads directory
    click Uploads "https://github.com/eddyy1410/gundam-sale-app/tree/master/uploads"

    classDef external fill:#cee5ff,stroke:#000
    classDef layer fill:#d4f5d4,stroke:#000
    classDef storage fill:#ffe4b5,stroke:#000
```
