# bxcodec/go-clean-arch architecture

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

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

## Overview

##### Project Type & Purpose
- This project is an example of implementing Clean Architecture in Go. It’s structured around domain-driven design with a clear separation between the delivery (interface) layer, use case/service layer, repository layer, and domain (entity) layer.
- The README outlines that the project follows Uncle Bob’s Clean Architecture principles, making it all about decoupling business rules from frameworks, UI, database, and external agencies.

##### Analyzing the File Structure
- Top-Level Directories and Files:
- "app/main.go": The application’s entry point.
- "domain/": Contains domain entities (e.g., article.go, author.go, errors.go). These define core business objects.
- "article/": Contains an example use case related to articles, including a service file and mock implementations.
- "internal/":
▪ "internal/rest/": Contains the REST delivery layer (e.g., article.go for HTTP endpoints and middleware for CORS and timeouts). This represents the outward-facing API.
▪ "internal/repository/": Houses repository implementations, especially under "internal/repository/mysql" which shows the concrete data storage (MySQL) implementations and tests.
▪ "internal/workers/": Space reserved for background jobs or asynchronous tasks.
- "misc/": Contains supporting Makefiles and tooling instructions.
- Configuration & Deployment Files:
- Dockerfile, compose.yaml, example.env, and .air.toml point to containerization, hot reloading, and environment configuration details.

##### Directions

a. Main Components:
- Entry Point: The "app" directory (main.go) acts as the starting point.
- Delivery/Interface Layer: Represented by “internal/rest” which handles HTTP requests and middleware.
- Use Case/Service Layer: Found in "article/service.go" and generally tied to executing business logic.
- Domain Model: The "domain" package encapsulates business entities such as Article and Author.
- Repository/Data Access Layer: "internal/repository/mysql" manages database interactions (with a corresponding SQL file, article.sql, to set up the database schema).
- Background Processing: "internal/workers" which may handle asynchronous tasks.
- Supporting Infrastructure: Tools such as Docker (Dockerfile, compose.yaml), testing (Makefile, mocks in both "article/mocks" and "internal/rest/mocks"), and CI (the GitHub workflows).

b. Relationships and Interactions:
- The Delivery Layer (REST APIs/controllers) receives external HTTP calls and invokes the Use Case/Service Layer.
- The Use Case/Service Layer coordinates with the Domain Model (business entities) and calls into the Repository Layer for data storage/retrieval from MySQL.
- Bidirectional interactions where needed (e.g., responses coming back up the chain).
- “Workers” as an independent component that interacts with core services, especially if there’s asynchronous processing.

c. Architectural Patterns/Design Principles:
- Clean Architecture layers (Domain, Usecase, Delivery, Repository) must be clearly delineated.
- Dependency inversion: Higher-level modules (services, controllers) depend on abstractions (interfaces defined within the domain or service layer) rather than concrete implementations. For example, repository interfaces might be implemented in the MySQL sub-package.
- How tests and mock implementations (present in the "mocks" directories) allow for isolation of components.

d. Relevant Technologies/Frameworks:
- Programming Language: Go (Golang)
- Frameworks/Libs: Interfaces for REST controllers, middleware (CORS, timeout), and repository pattern usage.
- Database: MySQL (as indicated by article.sql and repository/mysql)
- DevOps Tools: Docker (Dockerfile, compose.yaml), CI workflows (GitHub Actions in .github/workflows), Makefiles for task automation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layers
    subgraph "Application Layers"
        E["Entry Point (app/main.go)"]:::entrypoint
        R["REST API Layer (internal/rest)"]:::rest
        S["Service Layer (article/service.go)"]:::service
        D["Domain Layer (domain/*)"]:::domain
        P["Repository (internal/repository/mysql)"]:::repository
        W["Background Workers (internal/workers)"]:::workers
    end

    %% Supporting Infrastructure & DevOps
    subgraph "Supporting Infrastructure & DevOps"
        Dk["Dockerfile"]:::devops
        C["Compose Config (compose.yaml)"]:::devops
        Env["Env Config (example.env)"]:::devops
        M["Make Automation (misc/)"]:::devops
    end

    %% Connections between Layers
    E -->|"init"| R
    R -->|"calls"| S
    S -->|"executes_business_logic"| D
    S -->|"stores_data"| P
    P -->|"retrieves_data"| S
    W -->|"triggers_tasks"| S

    %% Connections from DevOps to Application Entry Point
    Dk -->|"configures"| E
    C -->|"orchestrates"| E
    Env -->|"sets_environment"| E
    M -->|"automates_tasks"| E

    %% Click Events for Components
    click E "https://github.com/bxcodec/go-clean-arch/blob/master/app/main.go"
    click R "https://github.com/bxcodec/go-clean-arch/tree/master/internal/rest/"
    click S "https://github.com/bxcodec/go-clean-arch/blob/master/article/service.go"
    click D "https://github.com/bxcodec/go-clean-arch/tree/master/domain/"
    click P "https://github.com/bxcodec/go-clean-arch/tree/master/internal/repository/mysql/"
    click W "https://github.com/bxcodec/go-clean-arch/tree/master/internal/workers/"
    click Dk "https://github.com/bxcodec/go-clean-arch/tree/master/Dockerfile"
    click C "https://github.com/bxcodec/go-clean-arch/blob/master/compose.yaml"
    click Env "https://github.com/bxcodec/go-clean-arch/blob/master/example.env"
    click M "https://github.com/bxcodec/go-clean-arch/tree/master/misc/"

    %% Styles
    classDef entrypoint fill:#f9c,stroke:#333,stroke-width:2px;
    classDef rest fill:#bbf,stroke:#333,stroke-width:2px;
    classDef service fill:#afa,stroke:#333,stroke-width:2px;
    classDef domain fill:#fdd,stroke:#333,stroke-width:2px;
    classDef repository fill:#ddf,stroke:#333,stroke-width:2px;
    classDef workers fill:#fcf,stroke:#333,stroke-width:2px;
    classDef devops fill:#ffd,stroke:#333,stroke-width:2px;
```
