# hpaes/go-api-project architecture

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

- Interactive diagram: https://gitdiagram.com/hpaes/go-api-project
- Repository: https://github.com/hpaes/go-api-project

## Overview

##### Project Type and Purpose
- This is a backend API service written in Go.
- It follows a Clean/Hexagonal architecture with clearly separated layers:
- API (controllers/handlers)
- Application (use cases)
- Domain (entities, value objects, domain errors)
- Infrastructure (database adapters, repositories, logging)

##### File Structure
- src/api
- controller – HTTP controllers (account_controller.go) and tests
- handler – generic HTTP handler for routing and error mapping
- response – structs for shaping JSON success responses
- src/core
- application/usecase – “interactors” (signup, get_account) and tests
- domain – core entities (Account) and value objects (Name, CPF, Email, CarPlate), plus domain‐specific errors
- errors – custom error types representing domain & HTTP error conditions
- src/infrastructure
- database – adapter interface and Postgres implementation (pq_adapter.go)
- repository – account repository implementation of domain interface
- logger – logging handler
- main.go – composition root: wire dependencies, start HTTP server

##### README
- Confirms: “Development of an API using golang”

##### Main Components & Their Interactions
a. Components
1. HTTP Client / External Consumer (Postman, Frontend)
2. API Layer
- Controllers (AccountController)
- Handlers (HTTP routing, error‐to‐response mapping)
- Response objects (SuccessResponse)
3. Application Layer
- Use cases (SignupUseCase, GetAccountUseCase)
4. Domain Layer
- Entities (Account)
- Value Objects (CPF, Email, Name, CarPlate)
- Domain Errors (AccountAlreadyExists, AccountNotFound, etc.)
5. Infrastructure Layer
- Repository interface (defined in domain or core)
- Repository implementation (AccountRepositoryImpl)
- Database adapter (DatabaseAdapter interface, PqAdapter)
- Logger (LoggerHandler)
6. External Systems
- PostgreSQL database

b. Relationships & Data Flow
1. HTTP Client → Controller
- HTTP POST /signup or GET /account
2. Controller → Handler
- Handler parses request, validates HTTP method & query/body, transforms to domain payload or returns HTTP error
3. Handler → Use Case
- Calls appropriate use case method with domain/value‐object parameters
4. Use Case → Repository Interface
- E.g., SignupUseCase calls AccountRepository.Save()
5. Repository Impl → Database Adapter
- AccountRepositoryImpl uses PqAdapter to execute SQL against PostgreSQL
6. Database ↔ PqAdapter
- Executes queries, returns results or DB‐level errors
7. Use Case → Domain Errors
- Throws domain errors on duplicates/not found, propagates up
8. Handler → Response
- Maps success or error into HTTP response (SuccessResponse or error JSON)
9. Controller → HTTP Client
- Returns JSON response

c. Architectural Patterns & Principles
- Clean (Hexagonal) Architecture separating core business logic from delivery and infrastructure.
- Dependency Inversion: use cases depend on repository interfaces, not implementations.
- Single Responsibility: each layer has a clear responsibility.

d. Key Technologies & Frameworks
- Go standard library (net/http) for HTTP server
- pq or pgx for PostgreSQL adapter
- Custom logger (could be wrapped around logrus or zap)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External
    HTTPClient["HTTP Client\n(Postman/Frontend)"]:::external

    %% Composition Root
    CompositionRoot["Composition Root\n(main.go)"]:::infra

    %% API Layer
    subgraph "API Layer" 
        direction TB
        AccountController["AccountController\n(src/api/controller)"]:::api
        Handler["Handler\n(src/api/handler)"]:::api
        SuccessResponse["SuccessResponse\n(src/api/response)"]:::api
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        SignupUseCase["SignupUseCase\n(src/core/application/usecase)"]:::app
        GetAccountUseCase["GetAccountUseCase\n(src/core/application/usecase)"]:::app
    end

    %% Domain Layer
    subgraph "Domain Layer"
        direction TB
        AccountEntity["Account Entity\n(src/core/domain/account.go)"]:::domain
        NameVO["Name VO\n(src/core/domain/valueObjects/name.go)"]:::domain
        CPFVO["CPF VO\n(src/core/domain/valueObjects/cpf.go)"]:::domain
        EmailVO["Email VO\n(src/core/domain/valueObjects/email.go)"]:::domain
        CarPlateVO["CarPlate VO\n(src/core/domain/valueObjects/car_plate.go)"]:::domain
        AccountExistsErr["AccountAlreadyExists Error\n(src/core/errors/account_already_exists_errr.go)"]:::domain
        AccountNotFoundErr["AccountNotFound Error\n(src/core/errors/account_not_found_err.go)"]:::domain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        DatabaseAdapter["«interface» DatabaseAdapter\n(src/infrastructure/database/database_adapter.go)"]:::infra
        PqAdapter["PqAdapter\n(src/infrastructure/database/pq_adapter.go)"]:::infra
        AccountRepoImpl["AccountRepositoryImpl\n(src/infrastructure/repository/account_repository_impl.go)"]:::infra
        LoggerHandler["LoggerHandler\n(src/infrastructure/logger/logger_handler.go)"]:::infra
    end

    %% Database
    PostgreSQL["PostgreSQL Database"]:::external

    %% Relationships
    HTTPClient -->|"HTTP POST /signup\nGET /account"| AccountController
    AccountController -->|"routes to"| Handler
    Handler -->|"parses & validates\n(SignupRequestDTO etc.)"| SignupUseCase
    Handler -->|"parses & validates\n(GetAccountRequestDTO)"| GetAccountUseCase
    SignupUseCase -->|"uses domain entity\nAccount Entity"| AccountEntity
    GetAccountUseCase -->|"uses domain entity\nAccount Entity"| AccountEntity
    SignupUseCase -->|"calls Save() on"| AccountRepoImpl
    GetAccountUseCase -->|"calls Find() on"| AccountRepoImpl
    AccountRepoImpl -->|"uses"| DatabaseAdapter
    DatabaseAdapter -->|"executes SQL"| PqAdapter
    PqAdapter -->|"queries"| PostgreSQL
    SignupUseCase -->|"throws"| AccountExistsErr
    GetAccountUseCase -->|"throws"| AccountNotFoundErr
    Handler -->|"maps success"| SuccessResponse
    Handler -->|"maps errors"| AccountExistsErr
    Handler -->|"maps errors"| AccountNotFoundErr
    CompositionRoot --> AccountController
    CompositionRoot --> PqAdapter
    CompositionRoot --> LoggerHandler
    CompositionRoot --> AccountRepoImpl

    %% Click Events
    click AccountController "https://github.com/hpaes/go-api-project/blob/main/src/api/controller/account_controller.go"
    click Handler "https://github.com/hpaes/go-api-project/blob/main/src/api/handler/handler.go"
    click SuccessResponse "https://github.com/hpaes/go-api-project/blob/main/src/api/response/success_response.go"
    click SignupUseCase "https://github.com/hpaes/go-api-project/blob/main/src/core/application/usecase/signup.go"
    click GetAccountUseCase "https://github.com/hpaes/go-api-project/blob/main/src/core/application/usecase/get_account.go"
    click AccountEntity "https://github.com/hpaes/go-api-project/blob/main/src/core/domain/account.go"
    click NameVO "https://github.com/hpaes/go-api-project/blob/main/src/core/domain/valueObjects/name.go"
    click CPFVO "https://github.com/hpaes/go-api-project/blob/main/src/core/domain/valueObjects/cpf.go"
    click EmailVO "https://github.com/hpaes/go-api-project/blob/main/src/core/domain/valueObjects/email.go"
    click CarPlateVO "https://github.com/hpaes/go-api-project/blob/main/src/core/domain/valueObjects/car_plate.go"
    click AccountExistsErr "https://github.com/hpaes/go-api-project/blob/main/src/core/errors/account_already_exists_errr.go"
    click AccountNotFoundErr "https://github.com/hpaes/go-api-project/blob/main/src/core/errors/account_not_found_err.go"
    click DatabaseAdapter "https://github.com/hpaes/go-api-project/blob/main/src/infrastructure/database/database_adapter.go"
    click PqAdapter "https://github.com/hpaes/go-api-project/blob/main/src/infrastructure/database/pq_adapter.go"
    click AccountRepoImpl "https://github.com/hpaes/go-api-project/blob/main/src/infrastructure/repository/account_repository_impl.go"
    click LoggerHandler "https://github.com/hpaes/go-api-project/blob/main/src/infrastructure/logger/logger_handler.go"
    click CompositionRoot "https://github.com/hpaes/go-api-project/blob/main/main.go"

    %% Styles
    classDef api fill:#cce5ff,stroke:#0366d6,color:#000
    classDef app fill:#d4edda,stroke:#28a745,color:#000
    classDef domain fill:#fff3cd,stroke:#856404,color:#000
    classDef infra fill:#ffe5b4,stroke:#e69500,color:#000
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#000
```
