# dowithlogic/golang-clean-architecture architecture

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

- Interactive diagram: https://gitdiagram.com/dowithlogic/golang-clean-architecture
- Repository: https://github.com/dowithlogic/golang-clean-architecture

## Overview

##### Project Identification and Main Purpose
- This project is a backend service implemented in Go, built using Clean Architecture principles and SOLID methodologies. It focuses on a layered structure separating concerns such as HTTP delivery, business logic (usecases), data models/entities (DTOs), and repository (data access layer).
- The README and file tree indicate the main sections as “Controller / Delivery”, “DTO”, “Usecase”, “Entity”, and “Repository”. There is an HTTP API built on top of the Echo framework and additional delivery mechanisms (Kafka, RPC).

##### Analyzing the File Structure
- Top-level directories:
- cmd/api: Contains the entry point for the API server.
- cmd/scheduler: Prepares for scheduled tasks (even if it’s a placeholder now).
- config: Contains YAML configurations and Go code for configuration management.
- database: Holds migration files (for MySQL) and likely tracks the schema.
- internal: Contains the core business logic and domain layers.
– Under internal, the “app” and “middleware” provide framework and cross-cutting concerns.
– The “users” folder is organized into further subdirectories (delivery, dtos, entities, repository, usecase, etc.) showing clear adherence to the Clean Architecture layers.
- pkg: Provides helper packages such as app_crypto, app_http, JWT, Redis, observability, etc. These illustrate infrastructure support (logging, tracing, error handling, and data source utilities).
- Other files like Dockerfile, docker-compose.yml, and Makefile indicate support for deployment, containerization, and automation.

##### Key Components to Capture
a. Application Layers (as defined by Clean Architecture):
- Delivery/Controller Layer: Represented by “internal/users/delivery/http/v1/handlers.go” (HTTP endpoints) and additional potential delivery methods like Kafka and RPC.
- Usecase/Application Layer: Implemented in “internal/users/usecase” and “internal/users/usecase.go”.
- Domain/Entity Layer: Found under “internal/users/entities” and “internal/users/dtos”.
- Infrastructure/Repository Layer: With “internal/users/repository” and its SQL queries and repository-test files.
b. Infrastructure and Configurations:
- Server: Use of Echo framework (observed in files such as internal/middleware/echo.go).
- Database: MySQL migrations under “database/mysql/migration”; data source utilities in pkg/datasource.
- External Services: Kafka delivery under “internal/users/delivery/kafka” suggests integration with a messaging system.
- Utility packages: JWT, Redis, observability, crypto utilities etc. are key support layers.

##### Establishing Relationships and Interactions
- The HTTP server (cmd/api) receives external requests and passes them to the controller layer.
- Controllers (delivery) use DTOs to capture incoming requests and delegate to the usecase layer.
- The usecase layer contains business logic which interacts with entities and uses repository abstractions to fetch/store data.
- Repositories interact with the database via SQL queries from pkg/datasource and migration scripts.
- Middleware components handle cross-cutting concerns like logging, error handling, cache management, and authentication (JWT).
- Additional service components (like scheduler and Kafka or RPC delivery options) integrate with the core business logic following similar layered interactions.
- Configuration management (via the “config” directory) and observability packages (logging, metrics, tracing) are used throughout to ensure consistency and maintainability.

##### Important Architectural Patterns and Design Principles
- Clean Architecture: Emphasize the separation of concerns by isolating domain logic from interface and infrastructure.
- SOLID Principles: Ensure that each component (such as usecases, entities, and repositories) has a single responsibility and depends on abstractions rather than concrete implementations.
- Layered Architecture: Clearly demarcate controllers, usecases, and repository layers, making the system modular and testable.
- Infrastructure abstraction: Using packages in pkg (for crypto, JWT, redis, datasource, etc.) to abstract external libraries.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% API Layer
    subgraph "API Layer"
        A["API Server (Entry Point)"]:::api
    end

    %% Delivery/Controller Layer
    subgraph "Delivery/Controller Layer"
        B1["HTTP Handlers (Echo)"]:::delivery
        B2["HTTP Routes (Echo)"]:::delivery
        C1["Kafka Delivery"]:::delivery
        C2["RPC Delivery"]:::delivery
    end

    %% Usecase/Application Layer
    subgraph "Usecase/Application Layer"
        D["Business Usecase"]:::usecase
    end

    %% Domain Layer
    subgraph "Domain Layer"
        E1["Domain Entities"]:::domain
        E2["DTO Objects"]:::domain
    end

    %% Repository/Data Access Layer
    subgraph "Repository/Data Access Layer"
        F["Repository - SQL"]:::repository
    end

    %% Database Layer
    subgraph "Database Layer"
        G["Database Migrations (MySQL)"]:::database
    end

    %% Infrastructure & Cross-Cutting Components
    subgraph "Infrastructure & Cross-Cutting"
        H["Middleware"]:::middleware
        I["Configuration"]:::config
        J["Scheduler"]:::scheduler
        K["Infrastructure Utilities"]:::infra
    end

    %% Main Flow Connections
    A -->|"calls"| B1
    A -->|"calls"| B2
    B1 -->|"routes"| D
    B2 -->|"routes"| D
    C1 -->|"calls"| D
    C2 -->|"calls"| D
    D -->|"uses"| E1
    D -->|"uses"| E2
    D -->|"calls"| F
    F -->|"queries"| G

    %% Cross-cutting and Infrastructure Connections
    A -->|"interceptedBy"| H
    H -->|"appliesTo"| B1
    H -->|"appliesTo"| D
    I -->|"configures"| A
    I -->|"configures"| H
    J -->|"triggers"| D
    F -->|"utilizes"| K
    H -->|"utilizes"| K

    %% Click Events
    click A "https://github.com/dowithlogic/golang-clean-architecture/blob/main/cmd/api/main.go"
    click B1 "https://github.com/dowithlogic/golang-clean-architecture/blob/main/internal/users/delivery/http/v1/handlers.go"
    click B2 "https://github.com/dowithlogic/golang-clean-architecture/blob/main/internal/users/delivery/http/v1/routes.go"
    click C1 "https://github.com/dowithlogic/golang-clean-architecture/tree/main/internal/users/delivery/kafka"
    click C2 "https://github.com/dowithlogic/golang-clean-architecture/tree/main/internal/users/delivery/rpc"
    click D "https://github.com/dowithlogic/golang-clean-architecture/blob/main/internal/users/usecase/usecase.go"
    click E1 "https://github.com/dowithlogic/golang-clean-architecture/tree/main/internal/users/entities"
    click E2 "https://github.com/dowithlogic/golang-clean-architecture/tree/main/internal/users/dtos"
    click F "https://github.com/dowithlogic/golang-clean-architecture/tree/main/internal/users/repository"
    click G "https://github.com/dowithlogic/golang-clean-architecture/tree/main/database/mysql/migration"
    click H "https://github.com/dowithlogic/golang-clean-architecture/tree/main/internal/middleware"
    click I "https://github.com/dowithlogic/golang-clean-architecture/tree/main/config"
    click J "https://github.com/dowithlogic/golang-clean-architecture/tree/main/cmd/scheduler"
    click K "https://github.com/dowithlogic/golang-clean-architecture/tree/main/pkg"

    %% Styles
    classDef api fill:#ADD8E6,stroke:#000,stroke-width:2px
    classDef delivery fill:#90EE90,stroke:#000,stroke-width:2px
    classDef usecase fill:#87CEEB,stroke:#000,stroke-width:2px
    classDef domain fill:#FFD700,stroke:#000,stroke-width:2px
    classDef repository fill:#FFA500,stroke:#000,stroke-width:2px
    classDef database fill:#FF6347,stroke:#000,stroke-width:2px
    classDef middleware fill:#DA70D6,stroke:#000,stroke-width:2px
    classDef config fill:#FFB6C1,stroke:#000,stroke-width:2px
    classDef scheduler fill:#D2B48C,stroke:#000,stroke-width:2px
    classDef infra fill:#D3D3D3,stroke:#000,stroke-width:2px
```
