# meysamhadeli/shop-golang-microservices architecture

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

- Interactive diagram: https://gitdiagram.com/meysamhadeli/shop-golang-microservices
- Repository: https://github.com/meysamhadeli/shop-golang-microservices

## Overview

##### Project type and purpose
- This is a distributed microservices system written in Go, demonstrating Vertical Slice Architecture, CQRS, Event-Driven Architecture, gRPC, RabbitMQ, Postgres, OpenTelemetry/Jaeger, OAuth2, and dependency injection (Uber-fx).
- It contains three independent microservices (“identity”, “product”, “inventory”), shared libraries under `internal/pkg`, and a Docker-Compose deployment for infrastructure.

##### File structure
- Top-level directories:
- `internal/pkg`: shared plumbing (HTTP server, gRPC client/server wrappers, RabbitMQ publisher/consumer, logging, tracing, OAuth2, utils).
- `internal/services/{identity,product,inventory}_service`: each microservice’s code, organized by Vertical Slice (feature folders) + CQRS (commands, queries, handlers, DTOs, endpoints).
- `deployments/docker-compose`: infrastructure YAML (Postgres, RabbitMQ, Jaeger).
- Each microservice has:
- `cmd/main.go`, `config/`, DI bootstrapping (`uber-fx`), `server/server.go` (Echo HTTP), gRPC server & client code, domain slices for each feature, repository implementations (GORM/Postgres), event publishers (RabbitMQ) and consumers (where relevant).

##### Extract architectural insights from README
- The system is microservices-based with:
- RESTful APIs (Echo + Swagger)
- Internal RPC (gRPC) for cross-service calls
- Asynchronous messaging (RabbitMQ) for eventual consistency
- CQRS + Mediator pattern (Go-MediatR) for segregation of commands/queries
- Distributed tracing (OpenTelemetry + Jaeger)
- OAuth2 for security
- Postgres per service; Outbox/Inbox patterns planned
- Docker-Compose orchestration of infra

##### Main components & their relationships
a. Components:
1. Client (REST UI or API consumer)
2. Identity Service
- HTTP/REST (Echo)
- gRPC server (protos)
- Postgres DB
- OAuth2 token endpoint
3. Product Service
- HTTP/REST (Echo)
- gRPC client to Identity Service for authentication/authorization
- RabbitMQ publisher (“ProductCreated”, “ProductUpdated”, etc.)
- Postgres DB
4. Inventory Service
- HTTP/REST (Echo)
- RabbitMQ consumer (listening to “ProductCreated” events; publishing “InventoryUpdated” events)
- Postgres DB
5. RabbitMQ Broker (message exchange)
6. OpenTelemetry Collector & Jaeger (distributed tracing)
7. Docker-Compose orchestrator

b. Relationships & data flows:
- Client →(HTTP/REST)→ Identity/Product/Inventory Service
- Product Service →(gRPC)→ Identity Service (to verify tokens/user info)
- Product Service →(RabbitMQ publish)→ “product.events” exchange
- Inventory Service →(RabbitMQ consume)→ “product.events” → update inventory → (optionally) publish “inventory.events”
- Each service → Postgres DB (read/write)
- Each service →(OpenTelemetry)→ Jaeger

c. Architectural patterns:
- Vertical Slice Architecture: each feature (e.g. CreateProduct) is a slice containing endpoint, DTOs, handler, repository.
- CQRS: separate command handlers (write) vs. query handlers (read).
- Mediator Pattern: endpoints dispatch commands/queries via Go-MediatR for pipeline behaviors (validation, logging, caching).
- Event-Driven: RabbitMQ for eventual consistency between services.
- gRPC: synchronous internal RPC for authentication/authorization.
- Outbox/Inbox (planned): for atomic event persistence and delivery.

d. Key technologies:
- Echo Framework (REST)
- GORM + Postgres (ORM & DB)
- grpc-go (gRPC)
- streadway/amqp (RabbitMQ client)
- open-telemetry/opentelemetry-go + Jaeger
- go-oauth2/oauth2
- Uber-fx (DI)
- Go-MediatR (Mediator)
- swaggo/echo-swagger
- Viper (config)
- Logrus (logging)

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client
    Client["Client UI/API Consumer"]:::client

    %% Identity Service
    subgraph "Identity Service" 
        direction TB
        ID_CLI["cmd/main.go"]:::service
        ID_Config["configurations"]:::service
        ID_Server["server/server.go (HTTP)"]:::service
        ID_gRPC["grpc_server/protos/*"]:::service
        ID_Repo["pg_user_repository.go"]:::service
        ID_OAuth["password_credentials.go"]:::service
    end

    %% Product Service
    subgraph "Product Service"
        direction TB
        PR_CLI["cmd/main.go"]:::service
        PR_Config["configurations"]:::service
        PR_Server["server/server.go (HTTP)"]:::service
        PR_gRPCClient["grpc_client/protos/*"]:::service
        PR_Repo["pg_product_repository.go"]:::service
        PR_Pub["events publisher"]:::service
        PR_SharedDelivery["product_delivery.go"]:::service
    end

    %% RabbitMQ Broker
    RabbitMQ["RabbitMQ Broker\n(product.events/inventory.events)"]:::broker

    %% Inventory Service
    subgraph "Inventory Service"
        direction TB
        IN_CLI["cmd/main.go"]:::service
        IN_Config["configurations"]:::service
        IN_Server["server/server.go (HTTP)"]:::service
        IN_Consumer["consumers (events/handlers)"]:::service
        IN_Repo["pg_inventory_repository.go"]:::service
        IN_SharedDelivery["inventory_delivery.go"]:::service
    end

    %% Shared Libraries
    subgraph "Shared Libraries (internal/pkg)"
        direction TB
        PKG_HTTP["http/echo/*"]:::shared
        PKG_gRPC["grpc/*"]:::shared
        PKG_RMQ["rabbitmq/*"]:::shared
        PKG_Logger["logger/logger.go"]:::shared
        PKG_OTel["otel/*"]:::shared
        PKG_OAuth2["oauth2/*"]:::shared
        PKG_Utils["mapper,utils,test,reflection"]:::shared
    end

    %% Datastores
    ID_DB["Identity Postgres"]:::db
    PR_DB["Product Postgres"]:::db
    IN_DB["Inventory Postgres"]:::db

    %% Observability
    Jaeger["Jaeger\n(OpenTelemetry)"]:::observability

    %% Client interactions
    Client -->|"HTTP/JSON"| ID_Server
    Client -->|"HTTP/JSON"| PR_Server
    Client -->|"HTTP/JSON"| IN_Server

    %% Identity gRPC for Product
    PR_Server -->|"gRPC"| ID_gRPC

    %% Messaging between Product and Inventory
    PR_Pub -->|"AMQP publish"| RabbitMQ
    RabbitMQ -->|"AMQP consume"| IN_Consumer

    %% Database interactions
    ID_Server -->|"GORM/Postgres"| ID_DB
    PR_Server -->|"GORM/Postgres"| PR_DB
    IN_Server -->|"GORM/Postgres"| IN_DB

    %% Observability
    ID_Server -->|"OTel"| Jaeger
    PR_Server -->|"OTel"| Jaeger
    IN_Server -->|"OTel"| Jaeger

    %% Shared libs usage
    ID_Server --> PKG_HTTP
    PR_Server --> PKG_HTTP
    IN_Server --> PKG_HTTP
    ID_gRPC --> PKG_gRPC
    PR_gRPCClient --> PKG_gRPC
    PR_Pub --> PKG_RMQ
    IN_Consumer --> PKG_RMQ
    ID_Server --> PKG_OAuth2

    %% Click Events: Identity
    click ID_CLI "https://github.com/meysamhadeli/shop-golang-microservices/blob/main/internal/services/identity_service/cmd/main.go"
    click ID_Server "https://github.com/meysamhadeli/shop-golang-microservices/blob/main/internal/services/identity_service/server/server.go"
    click ID_gRPC "https://github.com/meysamhadeli/shop-golang-microservices/tree/main/internal/services/identity_service/identity/grpc_server/protos/"
    click ID_Config "https://github.com/meysamhadeli/shop-golang-microservices/tree/main/internal/services/identity_service/configurations/"
    click ID_Repo "https://github.com/meysamhadeli/shop-golang-microservices/blob/main/internal/services/identity_service/identity/data/repositories/pg_user_repository.go"
    click ID_OAuth "https://github.com/meysamhadeli/shop-golang-microservices/blob/main/internal/pkg/oauth2/password_credentials.go"

    %% Click Events: Product
    click PR_CLI "https://github.com/meysamhadeli/shop-golang-microservices/blob/main/internal/services/product_service/cmd/main.go"
    click PR_Server "https://github.com/meysamhadeli/shop-golang-microservices/blob/main/internal/services/product_service/server/server.go"
    click PR_gRPCClient "https://github.com/meysamhadeli/shop-golang-microservices/tree/main/internal/services/product_service/product/grpc_client/protos/"
    click PR_Config "https://github.com/meysamhadeli/shop-golang-microservices/tree/main/internal/services/product_service/configurations/"
    click PR_Repo "https://github.com/meysamhadeli/shop-golang-microservices/blob/main/internal/services/product_service/product/data/repositories/pg_product_repository.go"
    click PR_Pub "https://github.com/meysamhadeli/shop-golang-microservices/tree/main/internal/services/product_service/product/features/*/events/"
    click PR_SharedDelivery "https://github.com/meysamhadeli/shop-golang-microservices/blob/main/internal/services/product_service/shared/delivery/product_delivery.go"

    %% Click Events: Inventory
    click IN_CLI "https://github.com/meysamhadeli/shop-golang-microservices/blob/main/internal/services/inventory_service/cmd/main.go"
    click IN_Server "https://github.com/meysamhadeli/shop-golang-microservices/blob/main/internal/services/inventory_service/server/server.go"
    click IN_Consumer "https://github.com/meysamhadeli/shop-golang-microservices/tree/main/internal/services/inventory_service/inventory/consumers/events/"
    click IN_Repo "https://github.com/meysamhadeli/shop-golang-microservices/blob/main/internal/services/inventory_service/inventory/data/repositories/pg_inventory_repository.go"
    click IN_SharedDelivery "https://github.com/meysamhadeli/shop-golang-microservices/blob/main/internal/services/inventory_service/shared/delivery/inventory_delivery.go"
    click IN_Config "https://github.com/meysamhadeli/shop-golang-microservices/tree/main/internal/services/inventory_service/configurations/"

    %% Click Events: Shared Libraries
    click PKG_HTTP "https://github.com/meysamhadeli/shop-golang-microservices/tree/main/internal/pkg/http/echo/"
    click PKG_gRPC "https://github.com/meysamhadeli/shop-golang-microservices/tree/main/internal/pkg/grpc/"
    click PKG_RMQ "https://github.com/meysamhadeli/shop-golang-microservices/tree/main/internal/pkg/rabbitmq/"
    click PKG_Logger "https://github.com/meysamhadeli/shop-golang-microservices/blob/main/internal/pkg/logger/logger.go"
    click PKG_OTel "https://github.com/meysamhadeli/shop-golang-microservices/tree/main/internal/pkg/otel/"
    click PKG_OAuth2 "https://github.com/meysamhadeli/shop-golang-microservices/tree/main/internal/pkg/oauth2/"
    click PKG_Utils "https://github.com/meysamhadeli/shop-golang-microservices/tree/main/internal/pkg/mapper/"

    classDef service fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef db fill:#e0f7e9,stroke:#047857,color:#047857;
    classDef broker fill:#FFE5B4,stroke:#D97706,color:#B45309;
    classDef observability fill:#F3E8FF,stroke:#7C3AED,color:#6D28D9;
    classDef client fill:#FFF1F2,stroke:#B91C1C,color:#B91C1C;
    classDef shared fill:#F0F9FF,stroke:#0369A1,color:#0369A1;
```
