# seastarlxy/ecommercesystem-microservices architecture

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

- Interactive diagram: https://gitdiagram.com/seastarlxy/ecommercesystem-microservices
- Repository: https://github.com/seastarlxy/ecommercesystem-microservices

## Overview

##### Project Type and Purpose
- This is a microservices‐based e-commerce backend (UserService as one of the services) written in C++20, employing asynchronous gRPC (wrapped by CallData) and REST via an Envoy API Gateway. It follows Domain-Driven Design (DDD) and layered architecture to deliver high performance, extensibility, and scalability.

##### Main Components
a. External Clients
- Web/mobile clients or other services making RESTful/HTTP requests.
b. API Gateway (Envoy)
- envoy.yaml handles inbound REST calls, translates to gRPC (via googleapis REST→gRPC transcoding).
c. UserService Microservice
- gRPC Server: `server/user_service_server.*`
- CallData Adapters (v1 & v2): asynchronous gRPC request handlers (`adapter/*`)
- Service Layer: `service/*` – business facades (AuthService, BasicUserService)
- Domain Layer: `domain/*` – domain entities (User), repository interfaces
- Infrastructure Layer:
- Persistence: PostgreSQL async pool (`infrastructure/persistence/postgresql/*`), DAOs (`.../dao`)
- State Storage: Redis client (`infrastructure/state_storage/redis_dao/*`)
- Threading: Asio thread pool (`infrastructure/asio_thread_pool/*`)
- Utilities: verification code generator, JWT, bcrypt, logging (spdlog) under `utils/*`
d. Datastores
- PostgreSQL (persistent user data)
- Redis (verification code/session caching)
e. CI/CD & Build
- GitHub Actions (`.github/workflows/ci.yml`)
- CMake (`UserService/CMakeLists.txt`)
- Docker & Docker Compose (`envBuild/*`)
- vcpkg for dependency management

##### Component Relationships & Data Flow
1. Client → Envoy API Gateway (REST)
2. Envoy → UserService gRPC endpoint
3. gRPC Server accepts request via CallData adapter →
4. Service Layer invokes Domain logic (entities + repository interfaces) →
5. Infrastructure Layer implements repositories:
- For user records: Async PostgreSQL connection pool → SQL DAOs
- For verification codes: Redis DAO
6. Results bubble back through Service → CallData → gRPC → Envoy → Client
7. Utilities (e.g., code generator, JWT) are invoked within Service/Domain as needed

##### Architectural Patterns & Principles
- Layered (Presentation/Adapter → Service → Domain → Infrastructure)
- Domain-Driven Design (rich domain models, repository interfaces)
- Asynchronous gRPC pattern using CRTP‐based CallData with object-pool managers
- Dependency Injection via Boost.DI
- Saga pattern (future work) for distributed transactions
- Containerization (Docker/Kubernetes) for microservices

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    Clients["External Clients (Web/Mobile)"]:::external

    %% API Gateway
    Gateway["Envoy API Gateway"]:::network
    click Gateway "https://github.com/seastarlxy/ecommercesystem-microservices/blob/main/apiGateway/envoy.yaml"
    ProtoDef["gRPC Service Definition"]:::network
    click ProtoDef "https://github.com/seastarlxy/ecommercesystem-microservices/blob/main/IDL/UserService/v1/user_service.proto"

    %% Microservice Container
    subgraph "UserService Microservice"
        direction TB

        %% API Layer
        subgraph "API Layer" 
            direction TB
            GRPCServer["UserService gRPC Server"]:::network
            click GRPCServer "https://github.com/seastarlxy/ecommercesystem-microservices/blob/main/UserService/server/user_service_server.cc"
            CallDataV1["CallData Adapter v1"]:::network
            click CallDataV1 "https://github.com/seastarlxy/ecommercesystem-microservices/blob/main/UserService/adapter/v1/src/register_call_data.cc"
            CallDataV2["CallData Adapter v2"]:::network
            click CallDataV2 "https://github.com/seastarlxy/ecommercesystem-microservices/blob/main/UserService/adapter/v2/call_data/src/register_call_data.cc"
        end

        %% Service Layer
        subgraph "Service Layer"
            direction TB
            AuthService["AuthService"]:::logic
            click AuthService "https://github.com/seastarlxy/ecommercesystem-microservices/blob/main/UserService/service/src/auth_service.cc"
            BasicUserService["BasicUserService"]:::logic
            click BasicUserService "https://github.com/seastarlxy/ecommercesystem-microservices/blob/main/UserService/service/src/basic_user_service.cc"
        end

        %% Domain Layer
        subgraph "Domain Layer"
            direction TB
            UserEntity["User Entity"]:::logic
            click UserEntity "https://github.com/seastarlxy/ecommercesystem-microservices/blob/main/UserService/domain/user.cc"
            IUserRepo["IUserRepository"]:::logic
            click IUserRepo "https://github.com/seastarlxy/ecommercesystem-microservices/blob/main/UserService/domain/interface/i_user_repository.h"
        end

        %% Infrastructure Layer
        subgraph "Infrastructure Layer"
            direction TB

            subgraph "Persistence (PostgreSQL)"
                PgPool["AsyncConnectionPool"]:::infra
                click PgPool "https://github.com/seastarlxy/ecommercesystem-microservices/blob/main/UserService/infrastructure/persistence/postgresql/src/async_connection_pool.cc"
                UserDAO["UserDAO"]:::infra
                click UserDAO "https://github.com/seastarlxy/ecommercesystem-microservices/blob/main/UserService/infrastructure/persistence/dao/user_dao.cc"
            end

            subgraph "State Storage (Redis)"
                RedisClient["RedisDAO"]:::infra
                click RedisClient "https://github.com/seastarlxy/ecommercesystem-microservices/blob/main/UserService/infrastructure/state_storage/redis_dao/redis_client.cc"
            end

            subgraph "Threading (Asio)"
                AsioPool["Asio ThreadPool"]:::infra
                click AsioPool "https://github.com/seastarlxy/ecommercesystem-microservices/blob/main/UserService/infrastructure/asio_thread_pool/asio_thread_pool.cc"
            end

            subgraph "Domain Impl"
                VerificationRepo["VerificationCodeRepository"]:::infra
                click VerificationRepo "https://github.com/seastarlxy/ecommercesystem-microservices/blob/main/UserService/infrastructure/domain_implement/src/verification_code_repository.cc"
            end
        end

        %% Utilities
        Utils["Utilities (JWT, bcrypt, logging)"]:::util
        click Utils "https://github.com/seastarlxy/ecommercesystem-microservices/blob/main/UserService/utils/src/verification_code_generator.cc"
    end

    %% Datastores
    subgraph "Datastores"
        direction TB
        Postgres["PostgreSQL"]:::db
        Redis["Redis"]:::db
    end

    %% CI/CD & Build
    subgraph "CI/CD & Build"
        direction TB
        CI["GitHub Actions"]:::ci
        click CI "https://github.com/seastarlxy/ecommercesystem-microservices/blob/main/.github/workflows/ci.yml"
        CMake["CMake"]:::ci
        click CMake "https://github.com/seastarlxy/ecommercesystem-microservices/blob/main/UserService/CMakeLists.txt"
        Docker["Docker & Compose"]:::ci
        click Docker "https://github.com/seastarlxy/ecommercesystem-microservices/blob/main/envBuild/v1/docker-compose.yml"
    end

    %% Flows
    Clients -->|"REST/HTTP"| Gateway
    Gateway -->|"REST→gRPC"| GRPCServer
    GRPCServer -->|"async gRPC"| CallDataV1
    GRPCServer -->|"async gRPC"| CallDataV2
    CallDataV1 -->|"invokes"| AuthService
    CallDataV1 -->|"invokes"| BasicUserService
    CallDataV2 -->|"invokes"| AuthService
    CallDataV2 -->|"invokes"| BasicUserService
    AuthService -->|"uses"| UserEntity
    BasicUserService -->|"uses"| UserEntity
    AuthService -->|"repository"| IUserRepo
    IUserRepo -->|"impl by"| PgPool
    IUserRepo -->|"impl by"| UserDAO
    BasicUserService -->|"uses"| VerificationRepo
    VerificationRepo -->|"uses"| RedisClient
    AuthService -->|"thread on"| AsioPool
    BasicUserService -->|"thread on"| AsioPool
    AuthService -->|"util"| Utils
    BasicUserService -->|"util"| Utils

    %% Storage connections
    PgPool --> Postgres
    UserDAO --> Postgres
    RedisClient --> Redis

    %% CI/CD flows
    CI --> CMake
    CMake --> Docker

    %% Classes
    classDef external fill:#f9f,stroke:#333,stroke-width:1px;
    classDef network fill:#bbf,stroke:#333,stroke-width:1px;
    classDef logic fill:#bfb,stroke:#333,stroke-width:1px;
    classDef infra fill:#fbf,stroke:#333,stroke-width:1px;
    classDef db fill:#ff9,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
    classDef util fill:#ffb,stroke:#333,stroke-width:1px;
    classDef ci fill:#ccc,stroke:#333,stroke-width:1px;
```
