System Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• deploys/README.md
• nest-cli.json
• apps/gateway/REFACTORING-GUIDE.md
• SETUP.md
• package.json
• QUICK_START.md

This document provides a high-level overview of the backend-luan-van e-commerce platform's architecture. The system is built using a microservices pattern with NestJS, a progressive Node.js framework. It is designed for scalability and maintainability by separating concerns into independent, deployable services.

The core of the architecture consists of an API Gateway that serves as the single entry point for all client requests, and a set of specialized microservices that handle specific business domains. Communication between the gateway and the microservices is managed asynchronously through a NATS message broker. Each service maintains its own dedicated PostgreSQL database, ensuring loose coupling and data isolation.

Sources: README.md:19-25, SETUP.md:105-120

Core Components

The system is structured as a monorepo containing multiple applications (microservices) and shared libraries.

Sources: nest-cli.json

Applications

The following table lists the primary applications (services) within the monorepo and their designated roles.

Service	Path	Description
Gateway	apps/gateway	The single entry point for all client requests. Handles authentication, rate limiting, audit logging, and request routing to other microservices.
User App	apps/user-app	Manages user accounts, authentication (JWT signing), and profiles.
Product App	apps/product-app	Manages product catalog, categories, and inventory.
Cart App	apps/cart-app	Manages user shopping carts.
Order App	apps/order-app	Manages order creation and processing.
Payment App	apps/payment-app	Handles payment processing logic.
AR App	apps/ar-app	Provides services related to Augmented Reality features.
Report App	apps/report-app	Responsible for generating reports.

Sources: nest-cli.json:10-80, README.md:20-21, apps/gateway/REFACTORING-GUIDE.md:20-35

Shared Libraries

A shared library is used to hold common code, types, and configurations used across multiple services.

Library	Path	Description
Shared	libs/shared	Contains shared modules, DTOs, types, and utilities (e.g., JWT service, error filters) to ensure consistency and reduce code duplication.

Sources: nest-cli.json:81-89, apps/gateway/REFACTORING-GUIDE.md:38-51

Communication and Data Flow

The system employs a decoupled communication pattern where the API Gateway communicates with backend microservices via a NATS message broker. Clients do not interact with microservices directly.

This diagram illustrates the high-level data flow from a client request to a microservice.

1. Client to Gateway: The client sends an HTTP request to the API Gateway.
2. Gateway Processing: The Gateway acts as a perimeter, performing initial validation, authentication (via JWT), rate limiting, and audit logging.
3. Gateway to NATS: Instead of making direct HTTP calls, the Gateway publishes a message (a request) to a specific subject on the NATS server.
4. NATS to Microservice: The relevant microservice, subscribed to that subject, receives the message.
5. Microservice to Database: The microservice processes the request, interacts with its dedicated database, and performs the required business logic.
6. Response Flow: For request-response patterns, the microservice publishes a reply to a dedicated reply subject, which the Gateway receives and then forwards back to the client as an HTTP response.

Sources: apps/gateway/REFACTORING-GUIDE.md:12-18, 60-70

Database Architecture

The architecture follows the Database-per-Service pattern. Each microservice has its own isolated PostgreSQL database, preventing tight coupling between services and allowing each service's schema to evolve independently.

This diagram shows the relationship between services and their dedicated databases.

Database connection strings are managed via environment variables, with each service having a unique variable (e.g., DATABASE_URL_USER, DATABASE_URL_PRODUCT).

Sources: QUICK_START.md:46-53

Security Model

The system implements a Perimeter Security model, where the API Gateway is the primary line of defense.

Sources: README.md:27-31, apps/gateway/REFACTORING-GUIDE.md:12-18

Key Security Features:

• Centralized Authentication: The API Gateway is solely responsible for authenticating incoming requests using RSA-based JSON Web Tokens (JWTs).
• Asymmetric JWTs: The user-app signs tokens with a private key, and the Gateway (along with other services if needed) verifies them with a public key. This ensures that only the user-app can issue valid tokens.
• Trust within the Perimeter: Microservices implicitly trust requests received from NATS, as they can only originate from the authenticated Gateway. This simplifies the microservices, which do not need to implement their own authentication guards.
• Perimeter Defenses: The Gateway also implements rate limiting to prevent DDoS/brute-force attacks and audit logging for security monitoring.

Sources: README.md:20, 27-31, apps/gateway/REFACTORING-GUIDE.md:100-120, SETUP.md:23-32

JWT Public Key Distribution

To enable JWT verification, the RSA public key must be distributed from the user-app (where keys are generated and stored) to the gateway. This is handled automatically at startup via NATS.

The following sequence diagram illustrates this process:

This automated distribution mechanism removes the need for manual key management and supports dynamic key rotation.

Sources: deploys/README.md:152-168, SETUP.md:23-32

Deployment Architecture

The entire system is designed to be deployed using Docker. Each microservice, along with the gateway, is containerized. The deployment documentation outlines a strategy where services can be deployed across multiple hosts.

This diagram shows the recommended deployment topology.

• Docker Images: Each service has a multi-stage Dockerfile to create optimized production images. These images are pushed to a container registry like Docker Hub.
• Infrastructure: PostgreSQL and NATS are run as separate, dedicated services, accessible over the network by all microservice containers.
• Deployment: Each host pulls the required Docker image and runs it as a container. Configuration is supplied via a .env file on each host.
• Startup Order: A critical startup order is defined to ensure system stability: PostgreSQL, then NATS, then user-app (to publish the JWT key), then the gateway, and finally all other services.

Sources: deploys/README.md:11-35, 192-200, QUICK_START.md:63-71