# dyhalmeida/go-clean-arch architecture

> Architecture diagram of the GitHub repository dyhalmeida/go-clean-arch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dyhalmeida/go-clean-arch
- Repository: https://github.com/dyhalmeida/go-clean-arch

## Overview

##### Project type and purpose
- This is a backend “Orders” microservice written in Go, demonstrating Clean Architecture.
- It exposes three protocols (HTTP REST, GraphQL, gRPC), persists orders in MySQL, publishes domain events over RabbitMQ, and is wired via Google Wire in `cmd/orders`.

##### File structure
- cmd/orders: application entrypoint, DI setup (`wire.go`), environment (.env) files.
- configs: environment‐variable loaders.
- internal/entity: core domain model (Order).
- internal/usecase: application/business logic (CreateOrder, ListOrder).
- internal/infra: adapter implementations
- database (MySQL repository + migrations)
- web (HTTP handlers + webserver starter)
- graph (gqlgen GraphQL server, schema, resolvers)
- grpc (proto definitions, generated pb, gRPC service implementation)
- internal/event: domain event definitions and handlers triggered after order creation.
- pkg/events: generic event dispatcher interface and RabbitMQ implementation.

##### README for additional insights
- Confirms use of Docker‐Compose (MySQL, RabbitMQ), Go 1.21+, GraphQL playground, gRPC via Evans CLI.
- Emphasizes Clean Architecture layered boundaries.

a. Main components
- External clients: REST clients (curl/Postman), GraphQL clients (Playground), gRPC clients (Evans).
- API Adapters:
- HTTP REST adapter (`internal/infra/web`)
- GraphQL adapter (`internal/infra/graph`)
- gRPC adapter (`internal/infra/grpc`)
- Application Core:
- Use Case layer (`internal/usecase`)
- Domain Entities (`internal/entity`)
- Infrastructure:
- Order Repository / MySQL (`internal/infra/database`)
- Event Dispatcher / RabbitMQ (`pkg/events`)
- Event Handlers (`internal/event/handler`)
- Composition Root / DI (`cmd/orders`, `configs`)

b. Relationships & data flow
1. Client → Adapter → Use Case → Entity → Repository → MySQL
2. Use Case emits OrderCreated event → Event Dispatcher → RabbitMQ
3. RabbitMQ → Event Handler → (optional follow‐on actions)
4. All dependencies are wired at startup by the DI container in `cmd/orders`.

c. Architectural patterns & design principles
- Clean/Onion Architecture: concentric layers with inward dependencies only.
- Hexagonal Ports & Adapters: adapters for HTTP, GraphQL, gRPC, DB, and message bus.
- Dependency Injection via Wire.
- Single Responsibility & Interface Segregation: each adapter, use case, and repository has a single, focused interface.

d. Key technologies & libraries
- Go (lang)
- Gin/HTTP (or net/http) for REST
- gqlgen for GraphQL
- gRPC + Protobuf
- MySQL (RDBMS)
- RabbitMQ (message broker)
- Docker & Docker Compose

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Clients
    subgraph "External Clients"
        RESTClient["REST Client\n(curl/Postman)"]:::external
        GraphQLClient["GraphQL Client\n(Playground)"]:::external
        gRPCClient["gRPC Client\n(Evans CLI)"]:::external
    end

    %% Adapters Layer
    subgraph "Adapters Layer"
        subgraph "HTTP REST Adapter"
            RESTHandler["order_handler.go"]:::adapter
            Webserver["starter.go\nwebserver.go"]:::adapter
        end
        subgraph "GraphQL Adapter"
            Schema["schema.graphqls"]:::adapter
            Resolver["resolver.go"]:::adapter
            Generated["generated.go"]:::adapter
            SchemaResolvers["schema.resolvers.go"]:::adapter
            Models["models_gen.go"]:::adapter
        end
        subgraph "gRPC Adapter"
            Proto["order.proto"]:::adapter
            PB1["order.pb.go"]:::adapter
            PB2["order_grpc.pb.go"]:::adapter
            Service["order_service.go"]:::adapter
        end
    end

    %% Core Application
    subgraph "Core Application"
        subgraph "Use Cases"
            CreateUC["create_order.go"]:::usecase
            ListUC["list_order.go"]:::usecase
        end
        subgraph "Entities"
            OrderEntity["order.go"]:::entity
            InterfaceEntity["interface.go"]:::entity
        end
    end

    %% Infrastructure
    subgraph "Infrastructure"
        DBRepo["order_repository.go"]:::infra
        Migrations["init.sql"]:::infra
        EventInterface["interface.go"]:::infra
        EventDispatcher["event_dispatcher.go"]:::infra
        EventDef["order_created.go"]:::infra
        EventHandler["order_created_handler.go"]:::infra
    end

    %% Config & Composition Root
    Config["config.go"]:::config
    CompositionMain["main.go\nwire.go\nwire_gen.go\n.env\n.env.example"]:::config

    %% External Systems
    MySQL[(MySQL)]:::db
    subgraph "Message Broker"
        Rabbit[(RabbitMQ)]:::mq
    end

    %% Connections
    RESTClient -->|POST /orders| RESTHandler
    RESTHandler -->|calls| CreateUC
    GraphQLClient -->|GraphQL| Schema
    Schema -->|resolver| CreateUC
    gRPCClient -->|CreateOrder RPC| Service
    Service -->|calls| CreateUC

    CreateUC -->|uses| OrderEntity
    ListUC -->|uses| OrderEntity

    CreateUC -->|persist| DBRepo
    ListUC -->|read| DBRepo
    DBRepo -->|SQL| MySQL

    CreateUC -->|Publish OrderCreated| EventDispatcher
    EventDispatcher -->|AMQP| Rabbit
    Rabbit -->|consume| EventHandler

    %% Composition wiring
    Config --> CompositionMain
    CompositionMain --> RESTHandler
    CompositionMain --> Webserver
    CompositionMain --> Schema
    CompositionMain --> Service
    CompositionMain --> CreateUC
    CompositionMain --> DBRepo
    CompositionMain --> EventDispatcher

    %% Click Events
    click CompositionMain "https://github.com/dyhalmeida/go-clean-arch/blob/main/cmd/orders/main.go"
    click CompositionMain "https://github.com/dyhalmeida/go-clean-arch/blob/main/cmd/orders/wire.go"
    click CompositionMain "https://github.com/dyhalmeida/go-clean-arch/blob/main/cmd/orders/wire_gen.go"
    click CompositionMain "https://github.com/dyhalmeida/go-clean-arch/blob/main/cmd/orders/.env"
    click CompositionMain "https://github.com/dyhalmeida/go-clean-arch/blob/main/cmd/orders/.env.example"
    click Config "https://github.com/dyhalmeida/go-clean-arch/blob/main/configs/config.go"
    click OrderEntity "https://github.com/dyhalmeida/go-clean-arch/blob/main/internal/entity/order.go"
    click InterfaceEntity "https://github.com/dyhalmeida/go-clean-arch/blob/main/internal/entity/interface.go"
    click CreateUC "https://github.com/dyhalmeida/go-clean-arch/blob/main/internal/usecase/create_order.go"
    click ListUC "https://github.com/dyhalmeida/go-clean-arch/blob/main/internal/usecase/list_order.go"
    click RESTHandler "https://github.com/dyhalmeida/go-clean-arch/blob/main/internal/infra/web/order_handler.go"
    click Webserver "https://github.com/dyhalmeida/go-clean-arch/blob/main/internal/infra/web/webserver/webserver.go"
    click Webserver "https://github.com/dyhalmeida/go-clean-arch/blob/main/internal/infra/web/webserver/starter.go"
    click Schema "https://github.com/dyhalmeida/go-clean-arch/blob/main/internal/infra/graph/schema.graphqls"
    click Resolver "https://github.com/dyhalmeida/go-clean-arch/blob/main/internal/infra/graph/resolver.go"
    click Generated "https://github.com/dyhalmeida/go-clean-arch/blob/main/internal/infra/graph/generated.go"
    click SchemaResolvers "https://github.com/dyhalmeida/go-clean-arch/blob/main/internal/infra/graph/schema.resolvers.go"
    click Models "https://github.com/dyhalmeida/go-clean-arch/blob/main/internal/infra/graph/model/models_gen.go"
    click Proto "https://github.com/dyhalmeida/go-clean-arch/blob/main/internal/infra/grpc/protofiles/order.proto"
    click PB1 "https://github.com/dyhalmeida/go-clean-arch/blob/main/internal/infra/grpc/pb/order.pb.go"
    click PB2 "https://github.com/dyhalmeida/go-clean-arch/blob/main/internal/infra/grpc/pb/order_grpc.pb.go"
    click Service "https://github.com/dyhalmeida/go-clean-arch/blob/main/internal/infra/grpc/service/order_service.go"
    click DBRepo "https://github.com/dyhalmeida/go-clean-arch/blob/main/internal/infra/database/order_repository.go"
    click Migrations "https://github.com/dyhalmeida/go-clean-arch/blob/main/internal/infra/database/migrations/init.sql"
    click EventInterface "https://github.com/dyhalmeida/go-clean-arch/blob/main/pkg/events/interface.go"
    click EventDispatcher "https://github.com/dyhalmeida/go-clean-arch/blob/main/pkg/events/event_dispatcher.go"
    click EventDef "https://github.com/dyhalmeida/go-clean-arch/blob/main/internal/event/order_created.go"
    click EventHandler "https://github.com/dyhalmeida/go-clean-arch/blob/main/internal/event/handler/order_created_handler.go"

    %% Styles
    classDef external fill:#f2f2f2,stroke:#333,stroke-width:1px
    classDef adapter fill:#cce5ff,stroke:#004085,stroke-width:1px
    classDef usecase fill:#d4edda,stroke:#155724,stroke-width:1px
    classDef entity fill:#fff3cd,stroke:#856404,stroke-width:1px
    classDef infra fill:#e2e3e5,stroke:#6c757d,stroke-width:1px
    classDef config fill:#ffeeba,stroke:#856404,stroke-width:1px
    classDef db fill:#d1ecf1,stroke:#0c5460,stroke-width:1px
    classDef mq fill:#f8d7da,stroke:#721c24,stroke-width:1px
```
