# ashhketchup/cec-microservices architecture

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

- Interactive diagram: https://gitdiagram.com/ashhketchup/cec-microservices
- Repository: https://github.com/ashhketchup/cec-microservices

## Overview

##### Project type and purpose
- This is a Go-based microservices e-commerce assignment that uses gRPC and gRPC-Gateway to expose services over HTTP and gRPC. It’s containerized with Docker and deployed via Kubernetes (you also have a docker-compose fallback).

##### File structure
- Top-level key dirs/files:
- services/ – contains each Go microservice (auth, cart, delivery, product) plus the API-Gateway service
- pkg/ – shared libraries (db, logger, middleware)
- k8s/ – Kubernetes manifests (namespaces, services, deployments, configs, secrets, volumes, ingress)
- docker-compose.yaml – for local compose-based deployment
- buf.yaml / buf.gen.yaml – proto compilation config
- Each service has:
- proto definitions → codegen under services/<svc>/proto/gen or services/api-gateway/gen
- Dockerfile + Go modules
- internal/db, internal/handler implementing business logic
- External infra: MySQL and Postgres init scripts in services/mysql/ and services/postgres/

##### Extract architecture insights from README
- All services communicate via gRPC. An API-Gateway (gRPC-Gateway) exposes HTTP endpoints by translating REST calls into gRPC.
- Kubernetes is used to host each service in its own Deployment + Service, with an Ingress/Gateway routing external traffic.
- Databases run as StatefulSets (MySQL, Postgres) with init jobs and PersistentVolumes.

##### Main components & interactions (to feature
a. API-Gateway
- Receives external HTTP/JSON requests
- Uses gRPC-Gateway handlers (gen code) to forward to microservices via internal gRPC endpoints
b. Microservices (Auth, Cart, Delivery, Product)
- Each runs a gRPC server
- Each has its own database:
- Auth, Cart, Delivery, Product → typically MySQL/Postgres instances (check config)
- Business logic in handler.go, data access in db/database.go
c. Databases
- MySQL and Postgres StatefulSets with init SQL jobs
- Secrets and ConfigMaps for credentials (k8s/secrets/*.yaml, k8s/configs/*.yaml)
d. Kubernetes Control Plane
- Namespaces isolate microservices
- Deployments manage pods per service
- Services (ClusterIP) route internal traffic
- Ingress/Gateway routes external traffic to the API-Gateway service

##### Relationships & data flow
- Client → Ingress (IngressController) → API-Gateway (HTTP port)
- API-Gateway → gRPC calls → Auth/Cart/Delivery/Product services
- Each service → SQL queries → its DB
- Optionally: inter-service calls (e.g., Cart might call Product or Auth) via gRPC

##### Architectural patterns & tech
- Microservices with bounded contexts
- API-Gateway pattern for unified HTTP interface
- gRPC + gRPC-Gateway for polyglot clients and strict contracts
- Kubernetes microservices orchestration (Deployments, Services, ConfigMaps, Secrets, Ingress)
- Docker for containerization

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["External Client"]:::external
    Client -->|HTTP/JSON| IngressController

    %% Kubernetes Cluster Boundary
    subgraph "Kubernetes Cluster"
        direction TB

        %% Ingress
        IngressController["Ingress Controller"]:::infra
        IngressController -->|routes to| APIGatewayService

        %% ConfigMaps & Secrets
        ConfigMaps["ConfigMaps"]:::config
        Secrets["Secrets"]:::secret

        %% API-Gateway
        subgraph "API-Gateway"
            direction TB
            APIGatewayService["API-Gateway Service (HTTP ↔ gRPC)"]:::service
            APIGatewayService -->|gRPC| AuthService
            APIGatewayService -->|gRPC| CartService
            APIGatewayService -->|gRPC| DeliveryService
            APIGatewayService -->|gRPC| ProductService
        end

        %% Microservices
        subgraph "Microservices"
            direction TB
            AuthService["Auth Service (gRPC)"]:::service
            CartService["Cart Service (gRPC)"]:::service
            DeliveryService["Delivery Service (gRPC)"]:::service
            ProductService["Product Service (gRPC)"]:::service
        end

        %% Databases
        subgraph "Stateful Databases"
            direction TB
            AuthDB["Auth DB (MySQL)"]:::db
            CartDB["Cart DB (MySQL)"]:::db
            DeliveryDB["Delivery DB (MySQL)"]:::db
            ProductDB["Product DB (Postgres)"]:::db
        end

        %% Service to DB connections
        AuthService -->|SQL| AuthDB
        CartService -->|SQL| CartDB
        DeliveryService -->|SQL| DeliveryDB
        ProductService -->|SQL| ProductDB

        %% Config & Secrets linkage
        ConfigMaps --> AuthService
        ConfigMaps --> CartService
        ConfigMaps --> DeliveryService
        ConfigMaps --> ProductService
        Secrets --> AuthService
        Secrets --> AuthDB
        Secrets --> ProductDB

    end

    %% Docker Compose Local Dev
    subgraph "Local Docker-Compose (Dev)"
        direction TB
        ComposeServices["Services & DBS via docker-compose"]:::compose
    end
    Client -->|HTTP| ComposeServices

    %% Legend
    subgraph "Legend"
        direction TB
        A["Rounded rectangle: Application/Service"]:::service
        B["Cylinder: Database"]:::db
        C["Document: ConfigMaps/Secrets"]:::config
        D["Orange: K8s infra"]:::infra
    end

    %% Click Events
    click APIGatewayService "https://github.com/ashhketchup/cec-microservices/tree/main/services/api-gateway/"
    click IngressController "https://github.com/ashhketchup/cec-microservices/blob/main/k8s/ingress/gateway.yaml"
    click APIGatewayService "https://github.com/ashhketchup/cec-microservices/blob/main/services/api-gateway/main.go"
    click APIGatewayService "https://github.com/ashhketchup/cec-microservices/tree/main/services/api-gateway/Dockerfile"
    click APIGatewayService "https://github.com/ashhketchup/cec-microservices/tree/main/services/api-gateway/gen/"
    click APIGatewayService "https://github.com/ashhketchup/cec-microservices/blob/main/k8s/services/api-gateway/deployment.yaml"

    click AuthService "https://github.com/ashhketchup/cec-microservices/tree/main/services/auth/"
    click AuthService "https://github.com/ashhketchup/cec-microservices/blob/main/services/auth/main.go"
    click AuthService "https://github.com/ashhketchup/cec-microservices/tree/main/services/auth/Dockerfile"
    click AuthService "https://github.com/ashhketchup/cec-microservices/blob/main/services/auth/internal/handler/auth_handler.go"
    click AuthService "https://github.com/ashhketchup/cec-microservices/blob/main/services/auth/internal/db/database.go"
    click AuthService "https://github.com/ashhketchup/cec-microservices/blob/main/k8s/services/auth/deployment.yaml"
    click AuthService "https://github.com/ashhketchup/cec-microservices/blob/main/k8s/configs/auth-config.yaml"
    click AuthService "https://github.com/ashhketchup/cec-microservices/blob/main/k8s/secrets/auth-secret.yaml"

    click CartService "https://github.com/ashhketchup/cec-microservices/tree/main/services/cart/"
    click CartService "https://github.com/ashhketchup/cec-microservices/blob/main/services/cart/main.go"
    click CartService "https://github.com/ashhketchup/cec-microservices/tree/main/services/cart/Dockerfile"
    click CartService "https://github.com/ashhketchup/cec-microservices/blob/main/services/cart/internal/handler/cart_handler.go"
    click CartService "https://github.com/ashhketchup/cec-microservices/blob/main/services/cart/internal/db/database.go"
    click CartService "https://github.com/ashhketchup/cec-microservices/blob/main/k8s/services/cart/deployment.yaml"
    click CartService "https://github.com/ashhketchup/cec-microservices/blob/main/k8s/configs/cart-config.yaml"

    click DeliveryService "https://github.com/ashhketchup/cec-microservices/tree/main/services/delivery/"
    click DeliveryService "https://github.com/ashhketchup/cec-microservices/blob/main/services/delivery/main.go"
    click DeliveryService "https://github.com/ashhketchup/cec-microservices/tree/main/services/delivery/Dockerfile"
    click DeliveryService "https://github.com/ashhketchup/cec-microservices/blob/main/services/delivery/internal/handler/delivery_handler.go"
    click DeliveryService "https://github.com/ashhketchup/cec-microservices/blob/main/services/delivery/internal/db/database.go"
    click DeliveryService "https://github.com/ashhketchup/cec-microservices/blob/main/k8s/services/delivery/deployment.yaml"
    click DeliveryService "https://github.com/ashhketchup/cec-microservices/blob/main/k8s/configs/delivery.yaml"

    click ProductService "https://github.com/ashhketchup/cec-microservices/tree/main/services/product/"
    click ProductService "https://github.com/ashhketchup/cec-microservices/blob/main/services/product/main.go"
    click ProductService "https://github.com/ashhketchup/cec-microservices/tree/main/services/product/Dockerfile"
    click ProductService "https://github.com/ashhketchup/cec-microservices/blob/main/services/product/internal/handler/product_handler.go"
    click ProductService "https://github.com/ashhketchup/cec-microservices/blob/main/services/product/internal/db/database.go"
    click ProductService "https://github.com/ashhketchup/cec-microservices/blob/main/k8s/services/product/deployment.yaml"
    click ProductService "https://github.com/ashhketchup/cec-microservices/blob/main/k8s/configs/product-config.yaml"

    click ConfigMaps "https://github.com/ashhketchup/cec-microservices/blob/main/k8s/configs/auth-config.yaml"
    click ConfigMaps "https://github.com/ashhketchup/cec-microservices/blob/main/k8s/configs/cart-config.yaml"
    click ConfigMaps "https://github.com/ashhketchup/cec-microservices/blob/main/k8s/configs/delivery.yaml"
    click ConfigMaps "https://github.com/ashhketchup/cec-microservices/blob/main/k8s/configs/product-config.yaml"
    click ConfigMaps "https://github.com/ashhketchup/cec-microservices/blob/main/k8s/configs/mysql-init-sql.yaml"
    click Secrets "https://github.com/ashhketchup/cec-microservices/blob/main/k8s/secrets/auth-secret.yaml"
    click Secrets "https://github.com/ashhketchup/cec-microservices/blob/main/k8s/secrets/mysql-secret.yaml"

    click AuthDB "https://github.com/ashhketchup/cec-microservices/blob/main/k8s/databases/mysql.yaml"
    click CartDB "https://github.com/ashhketchup/cec-microservices/blob/main/k8s/databases/mysql.yaml"
    click DeliveryDB "https://github.com/ashhketchup/cec-microservices/blob/main/k8s/databases/mysql.yaml"
    click ProductDB "https://github.com/ashhketchup/cec-microservices/blob/main/k8s/databases/postgres.yaml"

    click ComposeServices "https://github.com/ashhketchup/cec-microservices/blob/main/docker-compose.yaml"
    click BufConfig "https://github.com/ashhketchup/cec-microservices/blob/main/buf.yaml"
    click BufConfig "https://github.com/ashhketchup/cec-microservices/blob/main/buf.gen.yaml"

    %% Styles
    classDef service fill:#D0E8FF,stroke:#0B69A3,stroke-width:2px;
    classDef db fill:#D0F5D0,stroke:#2E7D32,stroke-width:2px;
    classDef infra fill:#FFE0B2,stroke:#F57C00,stroke-width:2px;
    classDef config fill:#FFF3E0,stroke:#FB8C00,stroke-width:2px,stroke-dasharray: 5 5;
    classDef secret fill:#FCE4EC,stroke:#C2185B,stroke-width:2px,stroke-dasharray: 5 5;
    classDef external fill:#F0F0F0,stroke:#888888,stroke-width:1px,stroke-dasharray:2 2;
    classDef compose fill:#E8EAF6,stroke:#3949AB,stroke-width:2px;
    class BufConfig,BufConfig,ComposeServices,Client external
    class APIGatewayService,AuthService,CartService,DeliveryService,ProductService service
    class AuthDB,CartDB,DeliveryDB,ProductDB db
    class IngressController,ConfigMaps,Secrets infra
    class ConfigMaps config
    class Secrets secret
    class ComposeServices compose
```
