Home
Relevant source files
The following files were used as context for generating this wiki page:This project is a comprehensive e-commerce platform built using a microservices architecture. It leverages a modern technology stack including NestJS for the server-side applications, NATS for inter-service communication, and Prisma as the ORM for PostgreSQL databases. The system is designed to be scalable, maintainable, and deployable via Docker containers.
The architecture consists of a central API Gateway that acts as the single entry point for all client requests, and a suite of specialized microservices, each responsible for a distinct business domain. This design promotes separation of concerns and allows for independent development, deployment, and scaling of each service. For more detailed setup instructions, see the Setup Guide.
Sources: README.md:19-27
Architecture
The system is designed around a microservices pattern, with a central API Gateway orchestrating communication between clients and the various backend services.
Sources: README.md:21-27, deploys/README.md:11-35
System Components
The following diagram illustrates the high-level architecture of the platform, showing the flow of requests from the client through the API Gateway to the various microservices and their dedicated databases.
This diagram shows the overall system architecture.
Sources: README.md:21-27, SETUP.md:121-139, deploys/README.md:11-35
Security Model
The project implements a Perimeter Security model. The API Gateway is the single point of control, responsible for authenticating all incoming requests using JWT. Once a request is authenticated and authorized by the gateway, it is considered trusted. The downstream microservices receive messages via NATS and do not perform their own authentication, simplifying their logic and relying on the gateway to enforce security.
Key security features include:
- JWT Authentication: The gateway uses RSA-based asymmetric JWTs. The
user-appsigns tokens with a private key, and the gateway verifies them with a public key distributed via NATS. - Rate Limiting: A middleware in the gateway prevents DDoS and brute-force attacks.
- Audit Logging: A middleware logs structured data for all requests, aiding in security monitoring and compliance.
Sources: README.md:29-34, apps/gateway/REFACTORING-GUIDE.md:10-16, apps/gateway/REFACTORING-GUIDE.md:78-100
Monorepo Structure
The project is organized as a monorepo using pnpm workspaces and managed by the NestJS CLI. This structure contains multiple applications (microservices and the gateway) and shared libraries.
| Project Name | Type | Path | Description |
|---|---|---|---|
gateway | application | apps/gateway | The main API Gateway and single entry point. |
user-app | application | apps/user-app | Manages users, authentication, and authorization. |
product-app | application | apps/product-app | Manages products, categories, and inventory. |
cart-app | application | apps/cart-app | Manages shopping carts. |
order-app | application | apps/order-app | Manages customer orders. |
payment-app | application | apps/payment-app | Handles payment processing. |
ar-app | application | apps/ar-app | Provides Augmented Reality features. |
report-app | application | apps/report-app | Generates reports and analytics. |
shared|library|libs/shared| Contains shared code, DTOs, and types. |
Sources: nest-cli.json, package.json:9-16
Getting Started (Local Development)
To set up the project for local development, follow these main steps. A more detailed guide is available in SETUP.md.
The following diagram outlines the local setup workflow.
Sources: SETUP.md:10-63
Key Scripts
The package.json file defines several scripts to streamline development, testing, and database management.
| Script | Description |
|---|---|
pnpm dev:all | Starts all microservices and the gateway in development watch mode. |
pnpm test | Runs all unit tests across the monorepo. |
pnpm test:e2e | Runs all end-to-end tests. |
pnpm test:full | Runs the full E2E test suite, including setting up test containers. |
pnpm build:all | Builds all applications for production. |
pnpm db:gen:all | Generates Prisma clients for all services. |
pnpm db:migrate:all | Runs database migrations for all services in a development environment. |
pnpm db:reset:all | Resets all databases by applying migrations from scratch. |
pnpm generate:keys | Generates the default RSA public/private key pair for JWT signing. |
Sources: package.json:7-35
Deployment
The application is designed to be deployed using Docker. The repository includes scripts and configuration for building and deploying each service as a separate container.
Deployment Flow
The deployment process involves building Docker images, pushing them to a registry (like Docker Hub), and then deploying them to the target hosts.
This diagram shows the sequence of steps for building and deploying a service.
Sources: QUICK_START.md:7-39, deploys/README.md:120-163
Startup Order
For the system to initialize correctly, services must be started in a specific order. This is critical for the gateway to receive the JWT public key from the user service.
- PostgreSQL Server
- NATS Server
- User-app (Waits 60 seconds, then publishes public key)
- Gateway (Waits 30 seconds to receive the key)
- Other services
Sources: QUICK_START.md:92-102
CI/CD Pipeline
The project uses GitHub Actions to automate building, testing, and publishing Docker images. Two primary workflows are defined.
Docker Build & Test Workflow
This workflow runs on every push or pull request to the main and develop branches.
This diagram shows the steps of the CI pipeline that runs on every push.
Sources: CI_CD_SETUP.md:5-20
Docker Push Workflow
This workflow runs on a push to the main branch or when a new Git tag is created (e.g., v1.0.0). It builds and pushes the final images to Docker Hub.
Sources: CI_CD_SETUP.md:22-31
Testing
The project includes a comprehensive testing strategy with unit and end-to-end tests. The goal is to achieve 100% test coverage.
- Unit Tests: Run with
pnpm test. These tests are located alongside the source code in.spec.tsfiles and use Jest. - End-to-End (E2E) Tests: Run with
pnpm test:e2e. A full E2E test environment, including databases, can be spun up usingpnpm test:full.
Sources: README.md:50-59, package.json:20-25, AGENTS.md:30-32