# huyhoang271005/backend architecture

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

- Interactive diagram: https://gitdiagram.com/huyhoang271005/backend
- Repository: https://github.com/huyhoang271005/backend

## Overview

1. **Overall shape**
   - This is a single Spring Boot 3 / Java 21 backend monolith for an e-commerce platform.
   - The code is organized into feature packages under `com.example.hello.Feature`, with shared cross-cutting code in `Infrastructure`, domain objects in `Entity`, and API/DTO mapping in `Mapper`.

2. **Request handling boundary**
   - HTTP entrypoints are grouped by feature controllers such as `AuthController`, `ProductController`, `OrderController`, `CartController`, `PaymentController`, `NotificationController`, `MessageController`, and others.
   - Most features follow the same flow: Controller → Service → Repository → Entity/DB, with DTOs used to isolate API contracts from persistence models.

3. **Domain and persistence model**
   - The persistent model lives in `Entity`, with core commerce tables like `Product`, `Variant`, `Category`, `Brand`, `Cart`, `Order`, `OrderItem`, `User`, `Role`, `Permission`, `Feedback`, `Notification`, `Message`, and chat/session-related entities.
   - The app uses many enums to encode business states and types, including `OrderStatus`, `CartStatus`, `UserStatus`, `PaymentMethod`, `RoleName`, `PermissionName`, `DeviceType`, and verification/token types.

4. **Catalog and product management**
   - Product structure is split across `ProductsManager`, `ProductDetail`, `Attribute`, `Brand`, and `Category`.
   - `ProductsManager` appears to handle CRUD and variant/attribute maintenance, while `ProductDetail` and `ProductSpecification` support catalog search/filtering and public-facing product views.
   - MapStruct-style mapper interfaces in `Mapper` convert product and variant entities into response DTOs.

5. **Shopping cart and checkout**
   - `CartController` and `CartService` manage cart state and cart items, using dedicated repositories for `Cart` and `CartItem`.
   - Cart DTOs include product variant details, showing the cart is variant-aware rather than just product-based.
   - The cart is a key bridge between catalog data and the order workflow.

6. **Orders and payment**
   - Orders are handled by `OrderController` and `OrderAdminController`, with separate services for customer and admin operations.
   - `OrderScheduled` suggests background order-state maintenance or cleanup.
   - Payment is integrated through `PaymentController`, `PaymentReturn`, and `VnPayService`, so checkout likely creates an order, redirects through VNPay, then processes the return callback to finalize payment state.

7. **Authentication and identity**
   - Authentication is a major subsystem: JWT-based security, OAuth2 login, refresh-token handling, and verification flows.
   - `AuthController`, `LoginService`, `RegisterService`, `VerifyService`, `TokenService`, and `Oauth2LoginSuccessHandle` coordinate login and account lifecycle.
   - `MyUserDetailsService`, JWT utilities, and security filters show Spring Security is used as the central authorization boundary.
   - RSA key files in `src/main/resources` indicate asymmetric signing/verification for tokens.

8. **User profile, sessions, and device tracking**
   - The `User` feature covers profile management, email management, sessions, and user-facing account endpoints.
   - `SessionService`, `DeviceRepository`, and the scheduled jobs under `Feature/User/Scheduled` indicate the system tracks active sessions and device metadata.
   - The readme’s device-warning email feature is reflected in the presence of email templates and device-related DTOs.

9. **Notifications, messaging, and real-time communication**
   - There are two real-time-ish channels: WebSocket configuration under `Infrastructure/Configuration/WebSocketConfig` and SSE support under `Infrastructure/External/SseEmitter`.
   - Notifications are persisted via `Notification` and `UserNotification`, then distributed through `NotificationService`, `NotificationScheduled`, and SSE.
   - Messaging and chat use `Message`, `RoomChat`, and join tables like `UserRoomChat`, with dedicated controllers/services and a security channel interceptor.

10. **Feedback and social interaction**
   - Feedback is modeled as a separate bounded area with `Feedback`, `FeedbackReply`, and `FeedbackOrderItem`.
   - This implies reviews are tied to completed order items rather than arbitrary products, which enforces purchase-based feedback rules.
   - `FeedbackValidator`, reply services, and DTOs show a controlled moderation/reply flow.

11. **Access control and roles/permissions**
   - Authorization is implemented as a role-permission system, not just coarse roles.
   - `RolePermissionInitializer` likely seeds the permission model, while repositories and services manage roles, permissions, and user-role assignment.
   - Caching support in `Infrastructure/Cache` includes role and permission caches, which suggests authorization reads are optimized heavily.

12. **Infrastructure and cross-cutting services**
   - `Infrastructure` contains shared constants, validation, exception handling, response wrappers, security config, CORS, cache config, and virtual-thread configuration.
   - External integrations include Cloudinary for media storage, SMTP/Thymeleaf-based email sending, and Caffeine caching.
   - Global exception handling and custom auth handlers form the standardized error/response boundary across all modules.

13. **Data transfer and mapping strategy**
   - The project uses many feature-specific DTOs and mapper interfaces to avoid exposing entities directly.
   - `Mapper` classes such as `UserMapper`, `OrderMapper`, `ProductMapper`, `FeedbackMapper`, `NotificationMapper`, and `SessionMapper` are the main transformation layer between persistence and API responses.
   - This keeps controller contracts stable while allowing the underlying entities to evolve.

14. **Runtime, deployment, and ops**
   - The app is built with Maven, includes a Dockerfile and docker-compose setup, and expects MSSQL as the database backend.
   - Configuration is environment-driven through `.env` and `application.yml`, with external secrets for mail, OAuth2, Cloudinary, and VNPay.
   - This is a backend service intended to run as a containerized API alongside supporting infrastructure rather than a standalone library.

15. **Testing footprint**
   - Tests currently focus on authentication and order services, which matches the two highest-risk workflows: identity and checkout.
   - The presence of service-level tests indicates the architecture is designed around testable service boundaries rather than controller-heavy logic.

Main entry points: [`src/main/java/com/example/hello/Feature/Authentication/Service/LoginService.java`](https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Feature/Authentication/Service/LoginService.java) (Auth), [`src/main/java/com/example/hello/Feature/Order/Service/OrderService.java`](https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Feature/Order/Service/OrderService.java) (Orders), [`src/main/java/com/example/hello/Infrastructure/Security/Config/SecurityConfig.java`](https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Infrastructure/Security/Config/SecurityConfig.java) (Security), [`src/main/java/com/example/hello/Feature/ProductsManager/Service/ProductService.java`](https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Feature/ProductsManager/Service/ProductService.java) (Catalog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API layer"]
end

subgraph group_commerce["Commerce"]
  node_catalog["Catalog<br/>product management"]
  node_browse["Browse<br/>search / detail"]
  node_cart["Cart<br/>[CartService.java]"]
  node_orders["Orders<br/>checkout / admin<br/>[OrderService.java]"]
  node_payment["Payment<br/>VNPay integration<br/>[VnPayService.java]"]
  node_feedback["Feedback<br/>reviews"]
end

subgraph group_identity["Identity"]
  node_auth["Auth<br/>login / token flow<br/>[LoginService.java]"]
  node_user["Users<br/>profile / session<br/>[UserService.java]"]
  node_roles["ACL<br/>roles / permissions"]
end

subgraph group_comm["Communication"]
  node_sse["SSE<br/>server-sent events<br/>[SseService.java]"]
  node_notify["Notify<br/>notifications"]
  node_chat["Chat<br/>messaging"]
  node_roomchat["Rooms"]
end

subgraph group_infra["Infrastructure"]
  node_app(("App"))
  node_security["Security"]
  node_jwt["JWT<br/>token signing<br/>[JwtComponent.java]"]
  node_exceptions["Errors<br/>global handling"]
  node_cloudinary["Media<br/>cloud storage"]
  node_email["Email<br/>smtp + templates"]
  node_mapping["Mappers<br/>DTO mapping<br/>[ProductMapper.java]"]
end

node_app -->|"boots with"| node_security
node_security -->|"uses"| node_jwt
node_security -->|"guards"| node_auth
node_security -->|"enforces"| node_roles
node_auth -->|"creates/loads"| node_user
node_auth -->|"sends"| node_email
node_auth -->|"issues"| node_jwt
node_user -->|"reads"| node_roles
node_catalog -->|"maps through"| node_mapping
node_browse -->|"reads from"| node_catalog
node_cart -->|"consumes"| node_catalog
node_cart -->|"maps through"| node_mapping
node_orders -->|"checks out"| node_cart
node_orders -->|"finalizes via"| node_payment
node_payment -->|"updates"| node_orders
node_feedback -->|"validates against"| node_orders
node_notify -->|"publishes via"| node_sse
node_chat -->|"coordinates"| node_roomchat
node_roomchat -->|"intercepts"| node_security
node_notify -.->|"alerts via"| node_email
node_catalog -->|"uploads media"| node_cloudinary
node_user -.->|"uploads media"| node_cloudinary
node_orders -->|"fails through"| node_exceptions
node_auth -->|"fails through"| node_exceptions

click node_app "https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/HelloApplication.java"
click node_security "https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Infrastructure/Security/Config/SecurityConfig.java"
click node_jwt "https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Infrastructure/Security/Jwt/JwtComponent.java"
click node_exceptions "https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Infrastructure/Exception/GlobalExceptionHandler.java"
click node_cloudinary "https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Infrastructure/External/Cloudinary/CloudinaryService.java"
click node_email "https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Infrastructure/External/Email/EmailSenderService.java"
click node_sse "https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Infrastructure/External/SseEmitter/SseService.java"
click node_auth "https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Feature/Authentication/Service/LoginService.java"
click node_user "https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Feature/User/Service/UserService.java"
click node_roles "https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Feature/RolePermission/Service/RolePermissionService.java"
click node_catalog "https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Feature/ProductsManager/Service/ProductService.java"
click node_browse "https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Feature/ProductDetail/Service/ProductDetailService.java"
click node_cart "https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Feature/Cart/CartService.java"
click node_orders "https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Feature/Order/Service/OrderService.java"
click node_payment "https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Feature/Payment/Service/VnPayService.java"
click node_feedback "https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Feature/Feedback/Service/FeedbackService.java"
click node_notify "https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Feature/Notification/NotificationService.java"
click node_chat "https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Feature/Message/MessageService.java"
click node_roomchat "https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Feature/RoomChat/RoomChatService.java"
click node_mapping "https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Mapper/ProductMapper.java"

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_catalog,node_browse,node_cart,node_orders,node_payment,node_feedback toneAmber
class node_auth,node_user,node_roles toneMint
class node_sse,node_notify,node_chat,node_roomchat toneRose
class node_app,node_security,node_jwt,node_exceptions,node_cloudinary,node_email,node_mapping toneIndigo
```

## Components

### Commerce

Catalog, cart, orders, payment, and feedback

- [Catalog](https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Feature/ProductsManager/Service/ProductService.java): product management · Product CRUD, variants, attributes, and async maintenance · `src/main/java/com/example/hello/Feature/ProductsManager/Service/ProductService.java`
- [Browse](https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Feature/ProductDetail/Service/ProductDetailService.java): search / detail · Public catalog listing and product detail queries · `src/main/java/com/example/hello/Feature/ProductDetail/Service/ProductDetailService.java`
- [Cart](https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Feature/Cart/CartService.java): shopping cart · Variant-aware cart state and item management · `src/main/java/com/example/hello/Feature/Cart/CartService.java`
- [Orders](https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Feature/Order/Service/OrderService.java): checkout / admin · Customer ordering, admin order management, and lifecycle jobs · `src/main/java/com/example/hello/Feature/Order/Service/OrderService.java`
- [Payment](https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Feature/Payment/Service/VnPayService.java): VNPay integration · Redirect and return callback handling for payment finalization · `src/main/java/com/example/hello/Feature/Payment/Service/VnPayService.java`
- [Feedback](https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Feature/Feedback/Service/FeedbackService.java): reviews · Purchase-based feedback and reply moderation · `src/main/java/com/example/hello/Feature/Feedback/Service/FeedbackService.java`

### Identity

Authentication, users, and authorization

- [Auth](https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Feature/Authentication/Service/LoginService.java): login / token flow · Login, registration, OAuth2, token refresh, and verification · `src/main/java/com/example/hello/Feature/Authentication/Service/LoginService.java`
- [Users](https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Feature/User/Service/UserService.java): profile / session · User profile, email, session, and device management · `src/main/java/com/example/hello/Feature/User/Service/UserService.java`
- [ACL](https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Feature/RolePermission/Service/RolePermissionService.java): roles / permissions · Role-permission administration and seeding · `src/main/java/com/example/hello/Feature/RolePermission/Service/RolePermissionService.java`

### Communication

Notifications, messaging, and real-time channels

- [SSE](https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Infrastructure/External/SseEmitter/SseService.java): server-sent events · Push channel for notifications and live updates · `src/main/java/com/example/hello/Infrastructure/External/SseEmitter/SseService.java`
- [Notify](https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Feature/Notification/NotificationService.java): notifications · Persisted notifications plus scheduled delivery and SSE fanout · `src/main/java/com/example/hello/Feature/Notification/NotificationService.java`
- [Chat](https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Feature/Message/MessageService.java): messaging · Room-based messaging and status tracking · `src/main/java/com/example/hello/Feature/Message/MessageService.java`
- [Rooms](https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Feature/RoomChat/RoomChatService.java): chat rooms · Room membership and conversation coordination · `src/main/java/com/example/hello/Feature/RoomChat/RoomChatService.java`

### Infrastructure

Shared security, caching, external integrations, and error handling

- [App](https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/HelloApplication.java): Spring Boot 3 / Java 21 · Application bootstrap and runtime entrypoint · `src/main/java/com/example/hello/HelloApplication.java`
- [Security](https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Infrastructure/Security/Config/SecurityConfig.java): Spring Security config · Authentication/authorization boundary with JWT filters and handlers · `src/main/java/com/example/hello/Infrastructure/Security/Config/SecurityConfig.java`
- [JWT](https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Infrastructure/Security/Jwt/JwtComponent.java): token signing · JWT component and asymmetric key handling · `src/main/java/com/example/hello/Infrastructure/Security/Jwt/JwtComponent.java`
- [Errors](https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Infrastructure/Exception/GlobalExceptionHandler.java): global handling · Shared exception translation and API error responses · `src/main/java/com/example/hello/Infrastructure/Exception/GlobalExceptionHandler.java`
- [Media](https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Infrastructure/External/Cloudinary/CloudinaryService.java): cloud storage · Product and profile media uploads through Cloudinary · `src/main/java/com/example/hello/Infrastructure/External/Cloudinary/CloudinaryService.java`
- [Email](https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Infrastructure/External/Email/EmailSenderService.java): smtp + templates · HTML email delivery for verification, welcome, and warnings · `src/main/java/com/example/hello/Infrastructure/External/Email/EmailSenderService.java`
- [Mappers](https://github.com/huyhoang271005/backend/blob/main/src/main/java/com/example/hello/Mapper/ProductMapper.java): DTO mapping · Entity-to-DTO transformation layer used across features · `src/main/java/com/example/hello/Mapper/ProductMapper.java`

## Connections

- App → Security: boots with · Application wires security and core infrastructure
- Security → JWT: uses · JWT authentication and token verification
- Security → Auth: guards · Security filters protect login and API access
- Security → ACL: enforces · Authorization is role/permission-based
- Auth → Users: creates/loads · Registration and login manage user identity state
- Auth → Email: sends · Verification and welcome emails
- Auth → JWT: issues · Access and refresh token handling
- Users → ACL: reads · Users are assigned roles and permissions
- Catalog → Mappers: maps through · Products and variants are exposed via DTOs
- Browse → Catalog: reads from · Public detail views are built from catalog data
- Cart → Catalog: consumes · Cart items reference product variants and attributes
- Cart → Mappers: maps through · Cart DTOs include variant-aware response shapes
- Orders → Cart: checks out · Orders are created from cart state
- Orders → Payment: finalizes via · Payment callback completes order state
- Payment → Orders: updates · VNPay return updates payment/order status
- Feedback → Orders: validates against · Feedback is tied to completed order items
- Notify → SSE: publishes via · Notifications are pushed to connected clients
- Chat → Rooms: coordinates · Messages are scoped to chat rooms and memberships
- Rooms → Security: intercepts · Channel security applies to realtime chat traffic
- Notify → Email: alerts via · Notification flows can trigger email delivery
- Catalog → Media: uploads media · Product assets are stored externally
- Users → Media: uploads media · Profile-related assets and device imagery
- Orders → Errors: fails through · Shared API error handling around checkout and admin flows
- Auth → Errors: fails through · Auth and verification errors are normalized
