# thnkrn/go-gin-clean-arch architecture

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

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

## Overview

##### Project Type and Purpose
- This is a backend RESTful API service built in Go, following the “Clean Architecture” (hexagonal/corporate) pattern.
- It uses Gin as the HTTP framework, GORM with PostgreSQL for persistence, JWT for authentication, Wire for dependency injection, Viper for configuration, and Swag for auto-generated Swagger docs.

##### File Structure Analysis
- cmd/api/main.go: entry point that initializes and starts the server.
- pkg/config: application configuration loader (Viper).
- pkg/db: database connection setup (GORM + PostgreSQL).
- pkg/di: Wire DI definitions.
- pkg/domain: core business entities and interfaces.
- pkg/repository: repository implementations and interfaces (data access layer).
- pkg/usecase: business logic orchestrators.
- pkg/api: HTTP layer, including router/server.go, handlers (user.go), middleware (auth.go), and docs.

##### Key README Insights
- Lists major technologies and their roles.
- Describes available REST endpoints (/, /login, /api/users, etc.).
- Shows Makefile targets for building, testing, DI generation, and Swagger generation.

##### Main Components
a. External Clients
- Web/mobile clients or curl/Postman invoking REST endpoints.
b. API Layer
- Gin HTTP router (pkg/api/server.go)
- Swagger docs endpoint (cmd/api/docs/*.yaml)
- HTTP middleware (JWT auth in pkg/api/middleware/auth.go)
- Handlers (pkg/api/handler/user.go)
c. Application Layer (Use Cases)
- Use case interface (pkg/usecase/interface/user.go)
- Use case implementation (pkg/usecase/user.go)
d. Domain Layer
- Domain entity definitions (pkg/domain/user.go)
e. Infrastructure Layer
- Repository interface (pkg/repository/interface/user.go)
- GORM-based repository implementation (pkg/repository/user.go)
- Database connection (pkg/db/connection.go)
f. Cross-cutting Services
- Configuration (Viper in pkg/config/config.go)
- Dependency Injection container (Wire in pkg/di/wire.go + wire_gen.go)
- Authentication (JWT library usage in middleware and handlers)

##### Relationships and Interactions
- Client → Gin Router → Middleware (auth) → Handlers
- Handlers → Use Case methods → Domain models
- Use Cases → Repository interfaces → GORM implementation → PostgreSQL
- At startup: main.go uses DI (Wire) to assemble Config → DB → Repositories → Use Cases → HTTP Server.
- Swagger docs are served via a Gin endpoint generated by swag.

##### Architectural Patterns and Principles
- Clean Architecture / Hexagonal: strict layer separation inward (depends on abstractions).
- Dependency Inversion: higher layers define interfaces, lower layers implement them.
- Single Responsibility: each package has a distinct concern.
- Convention over configuration: Makefile, Go modules, standard folder layout.

- Layers clearly separated and labeled (Framework / Adapters / Application / Domain).
- Notes on configuration loading and DI graph generation at startup.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    Client["External Clients"]:::external

    %% Frameworks & Tools Layer
    subgraph "Frameworks & Tools"
        Viper["Viper (Config)"]:::frameworks
        Wire["Wire (DI)"]:::frameworks
        Gin["Gin (HTTP Framework)"]:::frameworks
        GORM["GORM (ORM)"]:::frameworks
        JWTLib["JWT Library"]:::frameworks
        Swag["Swag (Swagger)"]:::frameworks
        Postgres["PostgreSQL DB"]:::frameworks
    end

    %% Interface / Adapters Layer
    subgraph "Interface / Adapters"
        Server["Gin Router / Server"]:::adapters
        AuthMW["Auth Middleware"]:::adapters
        UserHandler["UserHandler"]:::adapters
        RepoInterface["UserRepository Interface"]:::adapters
        RepoImpl["UserRepositoryImpl"]:::adapters
        DBConn["DB Connection"]:::adapters
        Main["main.go (Entry Point)"]:::adapters
        SwaggerDoc["Swagger Docs Endpoint"]:::adapters
    end

    %% Application / Use Cases Layer
    subgraph "Application / Use Cases"
        UserUsecaseInt["UserUsecase Interface"]:::usecase
        UserUsecase["UserUsecase Implementation"]:::usecase
    end

    %% Domain Core Layer
    subgraph "Domain Core"
        UserEntity["User Entity"]:::domain
    end

    %% Data Flows and Dependencies
    Client -->|"HTTP Request"| Server
    Server -->|"middleware"| AuthMW
    AuthMW -->|"validated JWT"| UserHandler
    UserHandler -->|"calls"| UserUsecaseInt
    UserUsecaseInt -->|"implemented by"| UserUsecase
    UserUsecase -->|"uses"| RepoInterface
    RepoInterface -->|"implemented by"| RepoImpl
    RepoImpl -->|"executes SQL"| Postgres
    UserUsecase -->|"manipulates"| UserEntity
    UserHandler -->|"returns JSON"| Client
    Server -->|"serves"| SwaggerDoc
    Main -->|"loads config via"| Viper
    Main -->|"initializes DB via"| DBConn
    Main -->|"sets up DI via"| Wire
    Main -->|"starts server"| Server

    %% Click Events
    click Server "https://github.com/thnkrn/go-gin-clean-arch/blob/master/pkg/api/server.go"
    click UserHandler "https://github.com/thnkrn/go-gin-clean-arch/blob/master/pkg/api/handler/user.go"
    click AuthMW "https://github.com/thnkrn/go-gin-clean-arch/blob/master/pkg/api/middleware/auth.go"
    click SwaggerDoc "https://github.com/thnkrn/go-gin-clean-arch/blob/master/cmd/api/docs/swagger.yaml"
    click UserUsecaseInt "https://github.com/thnkrn/go-gin-clean-arch/blob/master/pkg/usecase/interface/user.go"
    click UserUsecase "https://github.com/thnkrn/go-gin-clean-arch/blob/master/pkg/usecase/user.go"
    click UserEntity "https://github.com/thnkrn/go-gin-clean-arch/blob/master/pkg/domain/user.go"
    click RepoInterface "https://github.com/thnkrn/go-gin-clean-arch/blob/master/pkg/repository/interface/user.go"
    click RepoImpl "https://github.com/thnkrn/go-gin-clean-arch/blob/master/pkg/repository/user.go"
    click DBConn "https://github.com/thnkrn/go-gin-clean-arch/blob/master/pkg/db/connection.go"
    click Viper "https://github.com/thnkrn/go-gin-clean-arch/blob/master/pkg/config/config.go"
    click Wire "https://github.com/thnkrn/go-gin-clean-arch/blob/master/pkg/di/wire.go"
    click Wire "https://github.com/thnkrn/go-gin-clean-arch/blob/master/pkg/di/wire_gen.go"
    click Main "https://github.com/thnkrn/go-gin-clean-arch/blob/master/cmd/api/main.go"

    %% Styles
    classDef frameworks fill:#add8e6,stroke:#000,stroke-width:1px;
    classDef adapters fill:#90ee90,stroke:#000,stroke-width:1px;
    classDef usecase fill:#ffffe0,stroke:#000,stroke-width:1px;
    classDef domain fill:#ffa500,stroke:#000,stroke-width:1px;
    classDef external fill:#d3d3d3,stroke:#000,stroke-width:1px;
```
