# mehdihadeli/go-food-delivery-microservices architecture

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

- Interactive diagram: https://gitdiagram.com/mehdihadeli/go-food-delivery-microservices
- Repository: https://github.com/mehdihadeli/go-food-delivery-microservices

## Overview

##### Project Type & Purpose
- This is a Go-based **microservices** system (“Go Food Delivery Microservices”) implementing
- Vertical Slice Architecture
- CQRS + Mediator Pattern
- Domain-Driven Design & Event Sourcing
- Event-Driven Architecture over RabbitMQ
- REST (via Echo + Swagger) & gRPC for sync calls
- Dependency Injection (uber-go/fx)
- Multiple data stores (Postgres, EventStoreDB, MongoDB, Elasticsearch, Redis)
- It comprises three independently deployable services:
- Catalog Read Service (CRUD + read caches)
- Catalog Write Service (DDD + Postgres + Outgoing Integration Events)
- Order Service (Event Sourcing + EventStoreDB + projections into Mongo/Elastic)
- Shared libraries live under `internal/pkg`, and API / protobuf / OpenAPI contracts under `api/`.

##### File‐Structure Insights
- **Top Level**:
- `api/` – OpenAPI specs & protobufs for all services
- `deployments/` – Docker-Compose & Kubernetes resources
- `internal/pkg/` – reusable packages (messaging, config, HTTP/gRPC framework, persistence adapters, logging, telemetry, test helpers)
- `services/` – three folders (`catalogreadservice`, `catalogwriteservice`, `orderservice`), each with:
– `cmd/app` (service entrypoint)
– `config` (Viper setups)
– `internal/...` (feature slices: commands/queries, handlers, DTOs, repos, integration events)
– `docs/swagger.yaml`, Dockerfile, tests (unit, integration, end-to-end)
- **Messaging**: RabbitMQ bus builders & connectors under `internal/pkg/core/messaging` and `internal/pkg/rabbitmq`.
- **Databases**: adapters for Postgres (`bun`, `postgrespgx`, `gorm`, `sqlx`), MongoDB, Redis, Elasticsearch, EventStoreDB.
- **Observability**: OpenTelemetry tracing & metrics pipelines in `internal/pkg/otel`, Prometheus/Grafana config under `deployments`.

##### Key Components & Interactions
a. **Clients** invoke service APIs (HTTP/REST or gRPC) →
b. **API Layer** (`Echo` endpoints or gRPC handlers) →
c. **Vertical Slice Handler** (CQRS command/query via `go-mediatr`) →
d. **Domain Logic**
- Write services persist to Postgres or EventStoreDB; publish integration events to RabbitMQ
- Read services query NoSQL stores (MongoDB, Elastic) or cache (Redis)
e. **Message Broker** (RabbitMQ) routes events → other service consumers → drives eventual consistency
f. **Projections**: Order service’s event store projections populate read models in Mongo/Elastic
g. **Sync gRPC**: used for direct RPC between services when needed

##### Architectural Patterns & Principles
- **Vertical Slice**: each feature folder holds its endpoint, DTOs, handler, domain model, repository
- **CQRS & Mediator**: clear separation of commands vs queries, decoupled via pipelines
- **Event Sourcing**: orders are persisted as streams of events in EventStoreDB
- **Event-Driven**: integration events for cross-service communication over RabbitMQ
- **Dependency Injection**: all components wired by `uber-go/fx` modules
- **DDD**: services structured around aggregates, entities, domain events

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    Client["Clients"]:::external

    %% Services
    subgraph "Microservices"
        CRS["Catalog Read Service"]:::microservice
        CWS["Catalog Write Service"]:::microservice
        OS["Order Service"]:::microservice
    end

    %% Shared Libraries
    subgraph "Shared Libraries"
        FX["DI (uber-go/fx)"]:::lib
        HTTP["HTTP Framework (Echo + Swagger)"]:::lib
        GRPC["gRPC Support"]:::lib
        MQCore["Core Messaging (CQRS/Mediator)"]:::lib
        RabbitLib["RabbitMQ Messaging"]:::lib
        ESDBLib["Event Sourcing (EventStoreDB)"]:::lib
        Adapters["Persistence Adapters"]:::lib
        ObservLib["Observability (OTel)"]:::lib
        Utils["Utils & Config"]:::lib
        OA_CR["OpenAPI: CatalogRead"]:::lib
        OA_CW["OpenAPI: CatalogWrite"]:::lib
        OA_OS["OpenAPI: Order"]:::lib
        PB_CW["Protobuf: CatalogWrite"]:::lib
        PB_OS["Protobuf: Order"]:::lib
        PB_CM["Protobuf: common.proto"]:::lib
    end

    %% External Systems
    RabbitMQ["RabbitMQ"]:::broker
    Postgres["Postgres"]:::datastore
    ESDB["EventStoreDB"]:::datastore
    Mongo["MongoDB"]:::datastore
    Elastic["Elasticsearch"]:::datastore
    Redis["Redis"]:::datastore
    Observ["Prometheus/Grafana/Jaeger"]:::observ

    %% Client requests
    Client -->|REST/gRPC| CRS
    Client -->|REST/gRPC| CWS
    Client -->|REST/gRPC| OS

    %% Service to Data Stores
    CRS -->|Query| Redis
    CRS -->|Query| Mongo
    CRS -->|Query| Elastic
    CWS -->|Write| Postgres
    CWS -->|Publish Events| RabbitMQ
    OS  -->|Event Store| ESDB
    OS  -->|Publish Projections| RabbitMQ
    ESDB -->|Projection→| Mongo
    ESDB -->|Projection→| Elastic
    RabbitMQ -->|Consume Events| CRS
    RabbitMQ -->|Consume Events| OS

    %% Bindings to Shared Libraries
    CRS --> FX
    CWS --> FX
    OS  --> FX
    CRS --> HTTP
    CWS --> HTTP
    OS  --> HTTP
    CRS --> GRPC
    CWS --> GRPC
    OS  --> GRPC
    CRS --> MQCore
    CWS --> MQCore
    OS  --> MQCore
    MQCore --> RabbitLib
    MQCore --> ESDBLib
    MQCore --> Adapters
    Adapters --> Postgres
    Adapters --> Mongo
    Adapters --> Elastic
    Adapters --> Redis
    Adapters --> ESDB
    FX --> Utils
    FX --> ObservLib
    ObservLib --> Observ
    HTTP --> OA_CR
    HTTP --> OA_CW
    HTTP --> OA_OS
    GRPC  --> PB_CW
    GRPC  --> PB_OS
    GRPC  --> PB_CM

    %% Click Events
    click CRS "https://github.com/mehdihadeli/go-food-delivery-microservices/tree/main/services/catalogreadservice"
    click CWS "https://github.com/mehdihadeli/go-food-delivery-microservices/tree/main/services/catalogwriteservice"
    click OS "https://github.com/mehdihadeli/go-food-delivery-microservices/tree/main/services/orderservice"
    click OA_CR "https://github.com/mehdihadeli/go-food-delivery-microservices/tree/main/api/openapi/catalogreadservice"
    click OA_CW "https://github.com/mehdihadeli/go-food-delivery-microservices/tree/main/api/openapi/catalogwriteservice"
    click OA_OS "https://github.com/mehdihadeli/go-food-delivery-microservices/tree/main/api/openapi/orderservice"
    click PB_CW "https://github.com/mehdihadeli/go-food-delivery-microservices/tree/main/api/protobuf/catalogwriteservice"
    click PB_OS "https://github.com/mehdihadeli/go-food-delivery-microservices/tree/main/api/protobuf/orderservice"
    click PB_CM "https://github.com/mehdihadeli/go-food-delivery-microservices/blob/main/api/protobuf/common.proto"
    click FX "https://github.com/mehdihadeli/go-food-delivery-microservices/blob/main/internal/pkg/fxapp/app_fx.go"
    click FX "https://github.com/mehdihadeli/go-food-delivery-microservices/blob/main/internal/pkg/fxapp/application_builder.go"
    click HTTP "https://github.com/mehdihadeli/go-food-delivery-microservices/tree/main/internal/pkg/http/customecho"
    click HTTP "https://github.com/mehdihadeli/go-food-delivery-microservices/blob/main/internal/pkg/http/http_fx.go"
    click GRPC "https://github.com/mehdihadeli/go-food-delivery-microservices/blob/main/internal/pkg/grpc/grpc_fx.go"
    click GRPC "https://github.com/mehdihadeli/go-food-delivery-microservices/blob/main/internal/pkg/grpc/server.go"
    click GRPC "https://github.com/mehdihadeli/go-food-delivery-microservices/blob/main/internal/pkg/grpc/client.go"
    click RabbitLib "https://github.com/mehdihadeli/go-food-delivery-microservices/blob/main/internal/pkg/rabbitmq/rabbitmq_fx.go"
    click RabbitLib "https://github.com/mehdihadeli/go-food-delivery-microservices/blob/main/internal/pkg/rabbitmq/bus/rabbitmq-bus.go"
    click RabbitLib "https://github.com/mehdihadeli/go-food-delivery-microservices/tree/main/internal/pkg/rabbitmq/consumer/"
    click RabbitLib "https://github.com/mehdihadeli/go-food-delivery-microservices/tree/main/internal/pkg/rabbitmq/producer/"
    click MQCore "https://github.com/mehdihadeli/go-food-delivery-microservices/tree/main/internal/pkg/core/cqrs"
    click MQCore "https://github.com/mehdihadeli/go-food-delivery-microservices/tree/main/internal/pkg/core/messaging"
    click ESDBLib "https://github.com/mehdihadeli/go-food-delivery-microservices/blob/main/internal/pkg/eventstroredb/event_store.go"
    click ESDBLib "https://github.com/mehdihadeli/go-food-delivery-microservices/blob/main/internal/pkg/eventstroredb/aggregate_store.go"
    click ESDBLib "https://github.com/mehdihadeli/go-food-delivery-microservices/tree/main/internal/pkg/es/contracts/store"
    click ESDBLib "https://github.com/mehdihadeli/go-food-delivery-microservices/blob/main/internal/pkg/es/projection_publisher.go"
    click Adapters "https://github.com/mehdihadeli/go-food-delivery-microservices/tree/main/internal/pkg/bun/postgres"
    click Adapters "https://github.com/mehdihadeli/go-food-delivery-microservices/tree/main/internal/pkg/postgrespgx"
    click Adapters "https://github.com/mehdihadeli/go-food-delivery-microservices/tree/main/internal/pkg/postgresgorm"
    click Adapters "https://github.com/mehdihadeli/go-food-delivery-microservices/blob/main/internal/pkg/mongodb/mongo_fx.go"
    click Adapters "https://github.com/mehdihadeli/go-food-delivery-microservices/tree/main/internal/pkg/mongodb/repository/"
    click Adapters "https://github.com/mehdihadeli/go-food-delivery-microservices/blob/main/internal/pkg/elasticsearch/elastic_fx.go"
    click Adapters "https://github.com/mehdihadeli/go-food-delivery-microservices/blob/main/internal/pkg/elasticsearch/elasticsearch.go"
    click Adapters "https://github.com/mehdihadeli/go-food-delivery-microservices/blob/main/internal/pkg/redis/redis_fx.go"
    click Adapters "https://github.com/mehdihadeli/go-food-delivery-microservices/blob/main/internal/pkg/redis/redis.go"
    click ObservLib "https://github.com/mehdihadeli/go-food-delivery-microservices/tree/main/internal/pkg/otel/tracing/"
    click ObservLib "https://github.com/mehdihadeli/go-food-delivery-microservices/tree/main/internal/pkg/otel/metrics/"
    click ObservLib "https://github.com/mehdihadeli/go-food-delivery-microservices/tree/main/deployments/docker-compose/monitoring"
    click ObservLib "https://github.com/mehdihadeli/go-food-delivery-microservices/tree/main/deployments/otelcollector"
    click Utils "https://github.com/mehdihadeli/go-food-delivery-microservices/blob/main/internal/pkg/config/configfx.go"
    click Utils "https://github.com/mehdihadeli/go-food-delivery-microservices/tree/main/internal/pkg/logger"
    click Utils "https://github.com/mehdihadeli/go-food-delivery-microservices/tree/main/internal/pkg/mapper"
    click Utils "https://github.com/mehdihadeli/go-food-delivery-microservices/tree/main/internal/pkg/utils"

    %% Styles
    classDef microservice fill:#cff,stroke:#036,stroke-width:2px;
    classDef datastore fill:#f9f,stroke:#900,stroke-width:2px;
    classDef broker fill:#fcf,stroke:#f30,stroke-width:2px,stroke-dasharray: 5 5;
    classDef observ fill:#cfc,stroke:#090,stroke-width:2px;
    classDef lib fill:#ccf,stroke:#00c,stroke-width:2px;
    classDef external fill:#eee,stroke:#999,stroke-width:1px,stroke-dasharray: 2 2;
```
