# rasadov/ecommerceapi architecture

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

- Interactive diagram: https://gitdiagram.com/rasadov/ecommerceapi
- Repository: https://github.com/rasadov/ecommerceapi

## Overview

##### Project type and purpose
- This is a **microservices-based e-commerce** platform.
- Language mix: Go-based services (Account, Product, Order, Payment, GraphQL API Gateway) + Python-based Recommender.
- Key capabilities: gRPC communication, Kafka event streaming, unified GraphQL gateway, ElasticSearch, PostgreSQL.

##### File structure
- Top-level microservice folders:
- account/
- product/
- order/
- payment/
- graphql/ (API gateway)
- recommender/ (Python consumer)
- Shared code under pkg/ (auth, middleware, kafka helpers).
- docker-compose.yaml + docker/ directory orchestrate all containers: services, Postgres, ES, Kafka, Zookeeper.
- Each service has client/, cmd/, config/, internal/, models/, proto/ subfolders → clear gRPC & modular structure.

##### Extract README insights
- Services overview: Account, Product, Order, Payment, Recommender, GraphQL gateway.
- Data stores: PostgreSQL (account, order, payment, recommender-replica), ElasticSearch (product).
- Kafka streams: Order & Product produce; Recommender consumes.
- GraphQL gateway stitches all gRPC services.

##### Main components & boundaries
A. Clients (browser/mobile)
B. API Gateway (GraphQL service)
1. Account Service (Go)
2. Product Service (Go)
3. Order Service (Go)
4. Payment Service (Go)
5. Recommender Service (Python)
D. Infrastructure Services:
- PostgreSQL cluster (account DB, order DB, payment DB, recommender-replica)
- ElasticSearch (product index)
- Kafka + Zookeeper
- External payment provider (third-party)

##### Relationships & data flows
- Clients → (HTTP) → GraphQL API Gateway
- Gateway → (gRPC) → each Go microservice
- Account/Product/Order/Payment services → (DB calls) → respective PostgreSQL or ElasticSearch
- Order & Product services → (Kafka producer) → Kafka topic(s)
- Recommender → (Kafka consumer) → subscribes to Product/Order topics → updates Postgres replica
- Payment service → (Webhook/gRPC) → order service (to update order status)
- All services containerized and networked via Docker Compose

##### Architectural patterns & design principles
- Microservices decomposition by business domain.
- API Gateway pattern (GraphQL for schema stitching).
- Event-driven architecture via Kafka (asynchronous, decoupled).
- gRPC for inter-service RPC (strongly typed, high-performance).
- Polyglot services (Go + Python).
- 12-factor & containerized deployment.

##### Technologies & frameworks callouts
- Go modules, gRPC + protobuf, gqlgen (GraphQL), Python gRPC client/server, SQL (Postgres), ElasticSearch, Kafka, Docker / Docker Compose.
- Shared libs: pkg/auth (JWT), pkg/kafka (producer), pkg/middleware.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients Layer
    subgraph "Clients"
        direction TB
        Browser["Browser/Mobile"]:::external
    end

    %% API Gateway Layer
    subgraph "API Gateway"
        direction TB
        API_Gateway["GraphQL API Gateway\n:8080"]:::gateway
    end

    Browser -->|"HTTP"| API_Gateway

    %% Microservices Layer
    subgraph "Microservices" 
        direction TB
        Account_Svc["Account Service"]:::service
        Product_Svc["Product Service"]:::service
        Order_Svc["Order Service"]:::service
        Payment_Svc["Payment Service"]:::service
        Recommender_Svc["Recommender Service"]:::python
    end

    API_Gateway -->|"gRPC"| Account_Svc
    API_Gateway -->|"gRPC"| Product_Svc
    API_Gateway -->|"gRPC"| Order_Svc
    API_Gateway -->|"gRPC"| Payment_Svc

    %% Infrastructure Layer
    subgraph "Infrastructure"
        direction TB
        subgraph "Databases"
            direction TB
            Postgres_Account["PostgreSQL\n(account DB)"]:::db
            Postgres_Order["PostgreSQL\n(order DB)"]:::db
            Postgres_Payment["PostgreSQL\n(payment DB)"]:::db
            Postgres_Replica["PostgreSQL\n(recommender-replica)"]:::db
            ES["ElasticSearch\n(product index)"]:::db
        end
        subgraph "Messaging"
            direction TB
            Kafka["Kafka"]:::broker
            Zookeeper["Zookeeper"]:::broker
        end
        External_Payment["External Payment Provider"]:::external
    end

    %% Docker Boundary
    subgraph "Docker Network / Docker Compose"
        direction TB
        API_Gateway
        Account_Svc
        Product_Svc
        Order_Svc
        Payment_Svc
        Recommender_Svc
        Postgres_Account
        Postgres_Order
        Postgres_Payment
        Postgres_Replica
        ES
        Kafka
        Zookeeper
        External_Payment
    end

    %% Service-DB connections
    Account_Svc -->|"SQL"| Postgres_Account
    Order_Svc -->|"SQL"| Postgres_Order
    Payment_Svc -->|"SQL"| Postgres_Payment
    Product_Svc -->|"HTTP"| ES
    Recommender_Svc -->|"SQL"| Postgres_Replica

    %% Event streaming
    Order_Svc -->|"- - -\nKafka Producer"| Kafka
    Product_Svc -->|"- - -\nKafka Producer"| Kafka
    Kafka -->|"- - -\nKafka Consumer"| Recommender_Svc

    %% Payment webhook to Order
    Payment_Svc -->|"gRPC / Webhook"| Order_Svc

    %% External payment call
    Payment_Svc -->|"HTTPS"| External_Payment

    %% Click Events
    click API_Gateway "https://github.com/rasadov/ecommerceapi/tree/master/graphql/"
    click Account_Svc "https://github.com/rasadov/ecommerceapi/tree/master/account/"
    click Product_Svc "https://github.com/rasadov/ecommerceapi/tree/master/product/"
    click Order_Svc "https://github.com/rasadov/ecommerceapi/tree/master/order/"
    click Payment_Svc "https://github.com/rasadov/ecommerceapi/tree/master/payment/"
    click Recommender_Svc "https://github.com/rasadov/ecommerceapi/tree/master/recommender/"
    click Shared "https://github.com/rasadov/ecommerceapi/tree/master/pkg/"
    click Docker_Comp "https://github.com/rasadov/ecommerceapi/blob/master/docker-compose.yaml"
    click Docker_Dir "https://github.com/rasadov/ecommerceapi/tree/master/docker/"

    %% Styles
    classDef service fill:#aed6f1,stroke:#2e86c1,color:#1b4f72
    classDef python fill:#d2b4de,stroke:#8e44ad,color:#512e5f
    classDef gateway fill:#aed6f1,stroke:#2874a6,color:#1b2631
    classDef db fill:#abebc6,stroke:#28b463,color:#145a32
    classDef broker fill:#f9e79f,stroke:#d4ac0d,color:#7d6608
    classDef external fill:#f5cba7,stroke:#d35400,color:#78281f
    class Shared pkg
    class Docker_Comp,docker Dir
    classDef default fill:#ffffff,stroke:#000000,color:#000000
```
