# fernandobrandan/ecommerce-ms architecture

> Architecture diagram of the GitHub repository fernandobrandan/ecommerce-ms, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fernandobrandan/ecommerce-ms
- Repository: https://github.com/fernandobrandan/ecommerce-ms

## Overview

##### Project Type and Purpose
- This is a full-stack, microservices-based e-commerce platform.
- The “front” folder contains the user-facing Node/Express/EJS application.
- The s0-Gateway folder holds the API Gateway (NGINX + Express).
- s1 through s6 are independent services: User, Product, Cart, Order, Payment, Notification.
- Each service exposes HTTP REST endpoints, has its own Dockerfile, TypeScript code, and connects to its own PostgreSQL database.

##### High-Level Architecture
- API Gateway (Nginx + Express) sits at the edge, load-balances and routes incoming HTTP/HTTPS requests.
- The Frontend Node/EJS app either calls the Gateway directly or is itself proxied behind Nginx.
- Six microservices perform domain-specific business logic:
- User Service
- Product Service
- Cart Service
- Order Service
- Payment Service (integrates MercadoPago via ngrok in development)
- Notification Service (sends emails via Nodemailer and SMS via Twilio)
- Each service uses its own PostgreSQL instance (DB per service pattern).
- Services can call each other synchronously over HTTP for cross-service workflows (e.g., Order Service calls Cart Service to fetch cart items).

##### Key Components
- External Clients (Browser or Mobile App)
- Nginx/API Gateway
- Frontend Service (Node/EJS)
- User Service + User_DB
- Product Service + Product_DB
- Cart Service + Cart_DB
- Order Service + Order_DB
- Payment Service + Payment_DB
- Notification Service (stateless, integrates SMTP & Twilio)
- External APIs: MercadoPago, Email SMTP server, Twilio SMS API
- Docker Network (each service runs in its own container)

##### Relationships and Data Flow
- Clients → Nginx/API Gateway (incoming HTTP)
- Gateway → Respective Service endpoints (userRoute, productRoute, etc.)
- Frontend → Gateway → Services (for dynamic data)
- Order Service → Cart Service (HTTP call)
- Order Service → User Service (to validate user)
- Payment Service → MercadoPago API (HTTPS)
- Notification Service → SMTP/Twilio (outgoing calls)
- Each Service → Its own PostgreSQL instance (via Sequelize ORM)

##### Architectural Patterns & Design Principles
- Microservices: independent deployable services, own codebase and database.
- API Gateway: unified entrypoint, request routing, load balancing.
- Database per Service: ensures loose coupling, service autonomy.
- Synchronous HTTP Communication: for simplicity, services call each other directly.
- Containerization with Docker: each service and gateway run in isolated containers.
- Future-proof: Kubernetes for orchestration, GitHub Actions for CI/CD.

d. To the right, arrange the six microservice containers horizontally.
f. Off to the side, add external APIs (MercadoPago, SMTP, Twilio).
- Client → Gateway → Frontend/Services.
- Service → Its DB.
- Payment Service → MercadoPago.
- Notification Service → SMTP/Twilio.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    CL["Clients (Browser/Mobile)"]:::external

    %% API Gateway Container
    subgraph "API Gateway Container" 
        direction TB
        GW["Nginx + Express (API Gateway)"]:::gateway
        GW_DK["Dockerfile"]:::dockerfile
        GW_CFG["Config"]:::config
    end

    %% Frontend Container
    subgraph "Frontend Container"
        direction TB
        FE["Node/EJS Frontend"]:::frontend
        FE_DK["Dockerfile"]:::dockerfile
        FE_IDX["front/src/index.ts"]:::code
    end

    %% Microservices Containers
    subgraph "Microservices"
        direction TB

        subgraph "User Service Container"
            US["User Service"]:::service
            UDB["User_DB"]:::db
            US_DK["Dockerfile"]:::dockerfile
            US_IDX["s1-UserService/src/index.ts"]:::code
        end

        subgraph "Product Service Container"
            PS["Product Service"]:::service
            PDB["Product_DB"]:::db
            PS_DK["Dockerfile"]:::dockerfile
            PS_IDX["s2-ProductService/src/index.ts"]:::code
        end

        subgraph "Cart Service Container"
            CS["Cart Service"]:::service
            CDB["Cart_DB"]:::db
            CS_DK["Dockerfile"]:::dockerfile
            CS_IDX["s6-CartService/src/index.ts"]:::code
        end

        subgraph "Order Service Container"
            OS["Order Service"]:::service
            ODB["Order_DB"]:::db
            OS_DK["Dockerfile"]:::dockerfile
            OS_IDX["s3-OrderService/src/index.ts"]:::code
        end

        subgraph "Payment Service Container"
            PA["Payment Service"]:::service
            PADB["Payment_DB"]:::db
            PA_DK["Dockerfile"]:::dockerfile
            PA_IDX["s4-PaymentService/src/index.ts"]:::code
        end

        subgraph "Notification Service Container"
            NS["Notification Service"]:::service
            NS_DK["Dockerfile"]:::dockerfile
            NS_IDX["s5-NotificationService/src/index.ts"]:::code
        end
    end

    %% External APIs
    MP["MercadoPago API"]:::external
    SMTP["SMTP Server"]:::external
    TW["Twilio SMS API"]:::external

    %% Connections
    CL -->|"HTTP/HTTPS"| GW
    GW -->|"routes to"| FE
    GW -->|"routes to"| US
    GW -->|"routes to"| PS
    GW -->|"routes to"| CS
    GW -->|"routes to"| OS
    GW -->|"routes to"| PA
    GW -->|"routes to"| NS

    FE -->|"HTTP/HTTPS"| GW

    US -->|"SQL"| UDB
    PS -->|"SQL"| PDB
    CS -->|"SQL"| CDB
    OS -->|"SQL"| ODB
    PA -->|"SQL"| PADB

    OS -->|"HTTP GET"| CS
    OS -->|"HTTP GET"| US

    PA -->|"- - - HTTPS"| MP
    NS -->|"- - - SMTP"| SMTP
    NS -->|"- - - SMS"| TW

    %% Click Events
    click GW "https://github.com/fernandobrandan/ecommerce-ms/blob/main/s0-Gateway/src/index.ts"
    click GW_CFG "https://github.com/fernandobrandan/ecommerce-ms/blob/main/s0-Gateway/src/config.ts"
    click GW_DK "https://github.com/fernandobrandan/ecommerce-ms/tree/main/s0-Gateway/Dockerfile"
    click FE_IDX "https://github.com/fernandobrandan/ecommerce-ms/blob/main/front/src/index.ts"
    click FE_DK "https://github.com/fernandobrandan/ecommerce-ms/tree/main/front/Dockerfile"
    click US_IDX "https://github.com/fernandobrandan/ecommerce-ms/blob/main/s1-UserService/src/index.ts"
    click US_DK "https://github.com/fernandobrandan/ecommerce-ms/tree/main/s1-UserService/Dockerfile"
    click PS_IDX "https://github.com/fernandobrandan/ecommerce-ms/blob/main/s2-ProductService/src/index.ts"
    click PS_DK "https://github.com/fernandobrandan/ecommerce-ms/tree/main/s2-ProductService/Dockerfile"
    click CS_IDX "https://github.com/fernandobrandan/ecommerce-ms/blob/main/s6-CartService/src/index.ts"
    click CS_DK "https://github.com/fernandobrandan/ecommerce-ms/tree/main/s6-CartService/Dockerfile"
    click OS_IDX "https://github.com/fernandobrandan/ecommerce-ms/blob/main/s3-OrderService/src/index.ts"
    click OS_DK "https://github.com/fernandobrandan/ecommerce-ms/tree/main/s3-OrderService/Dockerfile"
    click PA_IDX "https://github.com/fernandobrandan/ecommerce-ms/blob/main/s4-PaymentService/src/index.ts"
    click PA_DK "https://github.com/fernandobrandan/ecommerce-ms/tree/main/s4-PaymentService/Dockerfile"
    click NS_IDX "https://github.com/fernandobrandan/ecommerce-ms/blob/main/s5-NotificationService/src/index.ts"
    click NS_DK "https://github.com/fernandobrandan/ecommerce-ms/tree/main/s5-NotificationService/Dockerfile"

    %% Styles
    classDef external fill:#d3d3d3,stroke:#666,stroke-width:1px
    classDef gateway fill:#a8ddb5,stroke:#2c7fb8,stroke-width:2px
    classDef frontend fill:#9ecae1,stroke:#08519c,stroke-width:2px
    classDef service fill:#fdae6b,stroke:#e6550d,stroke-width:2px
    classDef db fill:#bcbddc,stroke:#756bb1,stroke-width:2px
    classDef dockerfile fill:#fff2a1,stroke:#d95f0e,stroke-width:1px,stroke-dasharray: 5 5
    classDef config fill:#fee0d2,stroke:#de2d26,stroke-width:1px
    classDef code fill:#edf8b1,stroke:#4d004b,stroke-width:1px
```
