How huyhoang271005/backend works
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: LoginService.java Auth · OrderService.java Orders · SecurityConfig.java Security · ProductService.java Catalog
Components 20
Commerce
Catalog, cart, orders, payment, and feedback
- Catalog · Product CRUD, variants, attributes, and async maintenance
src/main/java/com/example/hello/Feature/ProductsManager/Service/ProductService.java - Browse · Public catalog listing and product detail queries
src/main/java/com/example/hello/Feature/ProductDetail/Service/ProductDetailService.java - Cart · Variant-aware cart state and item management
src/main/java/com/example/hello/Feature/Cart/CartService.java - Orders · Customer ordering, admin order management, and lifecycle jobs
src/main/java/com/example/hello/Feature/Order/Service/OrderService.java - Payment · Redirect and return callback handling for payment finalization
src/main/java/com/example/hello/Feature/Payment/Service/VnPayService.java - Feedback · Purchase-based feedback and reply moderation
src/main/java/com/example/hello/Feature/Feedback/Service/FeedbackService.java
Identity
Authentication, users, and authorization
- Auth · Login, registration, OAuth2, token refresh, and verification
src/main/java/com/example/hello/Feature/Authentication/Service/LoginService.java - Users · User profile, email, session, and device management
src/main/java/com/example/hello/Feature/User/Service/UserService.java - ACL · Role-permission administration and seeding
src/main/java/com/example/hello/Feature/RolePermission/Service/RolePermissionService.java
Communication
Notifications, messaging, and real-time channels
- SSE · Push channel for notifications and live updates
src/main/java/com/example/hello/Infrastructure/External/SseEmitter/SseService.java - Notify · Persisted notifications plus scheduled delivery and SSE fanout
src/main/java/com/example/hello/Feature/Notification/NotificationService.java - Chat · Room-based messaging and status tracking
src/main/java/com/example/hello/Feature/Message/MessageService.java - 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 · Application bootstrap and runtime entrypoint
src/main/java/com/example/hello/HelloApplication.java - Security · Authentication/authorization boundary with JWT filters and handlers
src/main/java/com/example/hello/Infrastructure/Security/Config/SecurityConfig.java - JWT · JWT component and asymmetric key handling
src/main/java/com/example/hello/Infrastructure/Security/Jwt/JwtComponent.java - Errors · Shared exception translation and API error responses
src/main/java/com/example/hello/Infrastructure/Exception/GlobalExceptionHandler.java - Media · Product and profile media uploads through Cloudinary
src/main/java/com/example/hello/Infrastructure/External/Cloudinary/CloudinaryService.java - Email · HTML email delivery for verification, welcome, and warnings
src/main/java/com/example/hello/Infrastructure/External/Email/EmailSenderService.java - Mappers · Entity-to-DTO transformation layer used across features
src/main/java/com/example/hello/Mapper/ProductMapper.java
Connections 24
- 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