# minhhoanq/ecommerce architecture

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

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

## Overview

##### Project type and purpose
- This is a microservices-based e-commerce backend platform. It consists of five domain services (Catalog, Order, Payment, User, Notification) plus an API Gateway and shared common libraries.
- Each domain service exposes gRPC endpoints (with Swagger/OpenAPI specs), persists to its own Postgres database, publishes and/or consumes Kafka events, and in some cases uses Redis or S3. The Payment service is implemented in TypeScript, the others in Go.

##### File structure
- Top-level folders:
- catalog_service, order_service, user_service, notification_service: Go microservices
- payment_service: Node/TypeScript microservice
- gateway: Go API gateway (HTTP→gRPC with grpc-gateway)
- common: shared constants, logger, utilities
- docker-compose.dev.yaml: brings up local Kafka, Postgres, Redis, S3-minio, and all services.
- Inside each Go service:
- api/: proto and swagger definitions
- cmd/: main.go to start gRPC (and HTTP gateway if applicable)
- configs/: DB, Kafka, gRPC, Redis, Mail, JWT setup
- internal/app: server bootstrap
- internal/dataaccess: DB migrations and clients, Kafka producers/consumers, Redis, S3
- internal/handler: gRPC handlers and inter-service gRPC clients
- internal/service: core business logic
- internal/initial: wiring and dependency injection
- Payment service mirrors similar layering in TS: src/config, src/dataaccess, src/modules, src/consumer, src/service, and proto under src/proto.

##### README for additional insights
- The README simply names the project “ecommerce,” confirming this is an end-to-end microservices system for an online store.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    Client["Web/Mobile Clients"]:::external
    Client -->|"HTTP/HTTPS"| APIGateway

    %% API Gateway
    subgraph "API Gateway"
        direction TB
        APIGateway["API Gateway (Go)\nHTTP REST → gRPC"]:::gateway
    end
    click APIGateway "https://github.com/minhhoanq/ecommerce/blob/main/gateway/cmd/main.go"
    click APIGateway "https://github.com/minhhoanq/ecommerce/tree/main/gateway/internal/app/gateway"
    click APIGateway "https://github.com/minhhoanq/ecommerce/tree/main/gateway/internal/routes"
    click APIGateway "https://github.com/minhhoanq/ecommerce/tree/main/gateway/internal/handler/grpc"
    click APIGateway "https://github.com/minhhoanq/ecommerce/blob/main/gateway/internal/initial/initial.go"

    %% Services Layer
    subgraph "Microservices"
        direction TB

        subgraph "Catalog Service"
            CAT["Catalog Service (Go)\ngRPC"]:::service
            click CAT "https://github.com/minhhoanq/ecommerce/blob/main/catalog_service/cmd/app/main.go"
            click CAT "https://github.com/minhhoanq/ecommerce/blob/main/catalog_service/api/catalog_service/catalog_service.proto"
            click CAT "https://github.com/minhhoanq/ecommerce/blob/main/catalog_service/internal/app/catalog_service/server.go"
            click CAT "https://github.com/minhhoanq/ecommerce/blob/main/catalog_service/internal/service/catalog.go"
            click CAT "https://github.com/minhhoanq/ecommerce/blob/main/catalog_service/internal/dataaccess/database/catalog.go"
            click CAT "https://github.com/minhhoanq/ecommerce/blob/main/catalog_service/internal/dataaccess/kafka/producer/producer.go"
            click CAT "https://github.com/minhhoanq/ecommerce/blob/main/catalog_service/internal/dataaccess/kafka/consumer/consumer.go"
            CAT -->|gRPC| PostgresCat
            CAT -->|produce user.created| Kafka
        end

        subgraph "Order Service"
            ORD["Order Service (Go)\ngRPC"]:::service
            click ORD "https://github.com/minhhoanq/ecommerce/blob/main/order_service/cmd/app/main.go"
            click ORD "https://github.com/minhhoanq/ecommerce/blob/main/order_service/api/order_service/order_service.proto"
            click ORD "https://github.com/minhhoanq/ecommerce/blob/main/order_service/internal/app/order_service/server.go"
            click ORD "https://github.com/minhhoanq/ecommerce/blob/main/order_service/internal/service/order.go"
            click ORD "https://github.com/minhhoanq/ecommerce/blob/main/order_service/internal/dataaccess/database/order.go"
            click ORD "https://github.com/minhhoanq/ecommerce/blob/main/order_service/internal/dataaccess/kafka/producer/order_created.go"
            click ORD "https://github.com/minhhoanq/ecommerce/blob/main/order_service/internal/handler/consumers/payment_transaction_completed.go"
            ORD -->|gRPC| PostgresOrd
            ORD -->|produce order.created| Kafka
            Kafka -->|consume payment.completed| ORD
        end

        subgraph "Payment Service"
            PAY["Payment Service (TS)\ngRPC + Kafka"]:::service
            click PAY "https://github.com/minhhoanq/ecommerce/blob/main/payment_service/src/main.ts"
            click PAY "https://github.com/minhhoanq/ecommerce/blob/main/payment_service/src/proto/payment_service.proto"
            click PAY "https://github.com/minhhoanq/ecommerce/blob/main/payment_service/src/cmd/start_grpc_server.ts"
            click PAY "https://github.com/minhhoanq/ecommerce/blob/main/payment_service/src/cmd/start_kafka_consumer.ts"
            click PAY "https://github.com/minhhoanq/ecommerce/blob/main/payment_service/src/modules/payment/payment_management_operators.ts"
            click PAY "https://github.com/minhhoanq/ecommerce/blob/main/payment_service/src/dataaccess/db/payment.ts"
            click PAY "https://github.com/minhhoanq/ecommerce/blob/main/payment_service/src/dataaccess/kafka/producer/payment_transaction_completed.ts"
            click PAY "https://github.com/minhhoanq/ecommerce/blob/main/payment_service/src/config/stripe.ts"
            PAY -->|gRPC| PostgresPay
            PAY -->|consume order.created| Kafka
            PAY -->|produce payment.completed| Kafka
            PAY -->|"Stripe API"| Stripe
        end

        subgraph "User Service"
            USR["User Service (Go)\ngRPC + JWT"]:::service
            click USR "https://github.com/minhhoanq/ecommerce/blob/main/user_service/cmd/app/main.go"
            click USR "https://github.com/minhhoanq/ecommerce/blob/main/user_service/api/user_service/user_service.proto"
            click USR "https://github.com/minhhoanq/ecommerce/blob/main/user_service/internal/app/user_service/server.go"
            click USR "https://github.com/minhhoanq/ecommerce/blob/main/user_service/internal/service/user.go"
            click USR "https://github.com/minhhoanq/ecommerce/blob/main/user_service/internal/dataaccess/database/user.go"
            click USR "https://github.com/minhhoanq/ecommerce/blob/main/user_service/internal/dataaccess/kafka/producer/user_created.go"
            click USR "https://github.com/minhhoanq/ecommerce/blob/main/user_service/internal/token/jwt_maker.go"
            USR -->|gRPC| PostgresUsr
            USR -->|produce user.created| Kafka
        end

        subgraph "Notification Service"
            NOTIF["Notification Service (Go)\nKafka → Email"]:::service
            click NOTIF "https://github.com/minhhoanq/ecommerce/blob/main/notification_service/cmd/app/main.go"
            click NOTIF "https://github.com/minhhoanq/ecommerce/blob/main/notification_service/api/notification_service/notification_service.proto"
            click NOTIF "https://github.com/minhhoanq/ecommerce/blob/main/notification_service/internal/app/notification_service/server.go"
            click NOTIF "https://github.com/minhhoanq/ecommerce/blob/main/notification_service/internal/handler/consumers/email_notify_completed.go"
            click NOTIF "https://github.com/minhhoanq/ecommerce/blob/main/notification_service/internal/email/sender.go"
            Kafka -->|consume user.created| NOTIF
            Kafka -->|consume payment.completed| NOTIF
            NOTIF -->|"SMTP/Email API"| SMTP
        end

    end

    %% Infrastructure
    subgraph "Platform Infrastructure"
        direction TB
        PostgresCat[(Postgres)]:::db
        PostgresOrd[(Postgres)]:::db
        PostgresPay[(Postgres)]:::db
        PostgresUsr[(Postgres)]:::db
        Redis[(Redis Cache)]:::cache
        S3[(S3 Object Store)]:::storage
        Kafka[(Kafka Cluster)]:::messaging
        Stripe["Stripe API"]:::external
        SMTP["SMTP/Email Provider"]:::external
    end

    %% Common Library
    Common["Common Library\n(constants, logger, utils)"]:::common
    click Common "https://github.com/minhhoanq/ecommerce/blob/main/common/constants/constants.go"
    click Common "https://github.com/minhhoanq/ecommerce/blob/main/common/logger/logger.go"
    click Common "https://github.com/minhhoanq/ecommerce/blob/main/common/utils/must.go"

    %% Connections
    APIGateway -->|gRPC| CAT
    APIGateway -->|gRPC| ORD
    APIGateway -->|gRPC| PAY
    APIGateway -->|gRPC| USR
    APIGateway -->|gRPC| NOTIF

    %% Styles
    classDef gateway fill:#FFD700,stroke:#333,stroke-width:1px
    classDef service fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef db fill:#98FB98,stroke:#333,stroke-width:1px,shape:cylinder
    classDef messaging fill:#F0E68C,stroke:#333,stroke-width:1px,shape:cloud
    classDef cache fill:#FFA07A,stroke:#333,stroke-width:1px,shape:cylinder
    classDef storage fill:#FFB6C1,stroke:#333,stroke-width:1px,shape:cylinder
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef common fill:#E6E6FA,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
```
