# lucassantoss1701/bank-api architecture

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

- Interactive diagram: https://gitdiagram.com/lucassantoss1701/bank-api
- Repository: https://github.com/lucassantoss1701/bank-api

## Overview

##### Project type and purpose
- This is a backend microservice (“Bank API”) written in Go. It exposes REST endpoints to manage bank accounts, query balances, perform transfers, and authenticate users. It follows a layered/clean-architecture style, with domain entities, use-cases, infrastructure adapters, and a main HTTP server.

##### File structure
- Top-level:
- cmd/server/main.go → application entrypoint, bootstraps configuration, database, web server
- configs/configs.go → configuration loader
- Dockerfile, docker-compose.yaml → containerization and service orchestration
- docs/swagger.{json,yaml} → OpenAPI spec
- internal/
– entity → domain models & repository interfaces
– usecase → application/business logic
– infra/database → DB connection, migrations, repository implementations
– infra/web → HTTP handlers, routing, middleware, response models

##### README
- Confirms endpoints (/login, /accounts, /transfers), features, how to run via Docker Compose, and OpenAPI URL.

##### Main components and their relationships
a. Clients & Tools
– External HTTP clients or Swagger UI → send HTTP requests
b. Web/API Layer
– Webserver (router + middleware: auth, logging)
– HTTP Handlers (account_handler, transfer_handler)
c. Application Layer
– Use-Cases (createAccount, login, makeTransfer, etc.)
– Coordinates domain logic and persistence
d. Domain Layer
– Entities (Account, Transfer) and repository interfaces
e. Infrastructure Layer
– Database Connection & Migrations (PostgreSQL)
– Repository Implementations (account_repository, transfer_repository)
f. Configuration & Bootstrapping
– Config loader reads env/flags
– Dependency injection in main.go wires up DB, repositories, use-cases, webserver
g. External Services
– PostgreSQL container
– (Optional) Monitoring, logging sinks

##### Architectural patterns & design principles
- Clean/Hexagonal Architecture:
- Layers are strictly separated: outer layers depend on inner layers only via interfaces.
- Entities are at the core; use-cases orchestrate them; infra implements interfaces.
- Dependency Injection at startup (main.go).
- Middleware implements cross-cutting concerns (auth, logging).
- Migrations ensure DB schema versioning.

8) Optionally, show “docker-compose” orchestrating API container + Postgres container.
9) Swagger spec file being served by the webserver.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    subgraph "Clients"
        ClientHTTP["External HTTP Client"]:::external
        SwaggerUI["Swagger UI"]:::docs
    end

    %% Configuration & Bootstrapping
    Config["Config Loader\n(configs/configs.go)"]:::config
    Main["Main (cmd/server/main.go)"]:::config

    %% Web/API Layer
    subgraph "Web/API Layer"
        Webserver["Webserver\n(router + middleware)"]:::web
        AuthMW["Auth Middleware"]:::web
        LogMW["Logging Middleware"]:::web
        AccountRoutes["Account Routes"]:::web
        TransferRoutes["Transfer Routes"]:::web
        AccountHandler["AccountHandler"]:::web
        TransferHandler["TransferHandler"]:::web
    end

    %% Application Layer
    subgraph "Application Layer"
        CreateAccountUC["UseCase: CreateAccount"]:::usecase
        LoginUC["UseCase: Login"]:::usecase
        FindAccountUC["UseCase: FindAccount"]:::usecase
        FindBalanceUC["UseCase: FindBalanceByAccount"]:::usecase
        FindTransfersUC["UseCase: FindTransfersByAccount"]:::usecase
        MakeTransferUC["UseCase: MakeTransfer"]:::usecase
    end

    %% Domain Layer
    subgraph "Domain Layer"
        AccountEntity["Entity: Account"]:::domain
        TransferEntity["Entity: Transfer"]:::domain
        CommonTypes["Common Types"]:::domain
        DomainErrors["Domain Errors"]:::domain
        RepoInterfaces["Repo Interfaces"]:::domain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        subgraph "Database Infra"
            DBConn["DB Connection & Migrations"]:::db
            AccountRepo["Postgres AccountRepo"]:::infra
            TransferRepo["Postgres TransferRepo"]:::infra
            RepoUtils["Repo Utilities"]:::infra
            PostgresDB["PostgreSQL DB"]:::db
        end
        subgraph "Web Infra"
            WebServerImpl["Webserver Impl"]:::infra
            Responses["HTTP Response Models"]:::infra
        end
    end

    %% Orchestration & Docs
    DockerCompose["docker-compose.yaml"]:::infra
    Dockerfile["Dockerfile"]:::infra
    SwaggerSpec["OpenAPI Spec\ndocs/swagger.{json,yaml}"]:::docs
    WaitScript["wait-for-services.sh"]:::infra
    Makefile["Makefile"]:::infra

    %% Connections: Clients to Web/API
    ClientHTTP -->|HTTP| Webserver
    SwaggerUI -->|Swagger UI| Webserver
    Webserver --> AuthMW
    Webserver --> LogMW
    Webserver --> AccountRoutes
    Webserver --> TransferRoutes
    AccountRoutes --> AccountHandler
    TransferRoutes --> TransferHandler

    %% Handlers to UseCases
    AccountHandler -->|"calls"| CreateAccountUC
    AccountHandler -->|"calls"| FindAccountUC
    AccountHandler -->|"calls"| FindBalanceUC
    TransferHandler -->|"calls"| MakeTransferUC
    TransferHandler -->|"calls"| FindTransfersUC
    AccountHandler -->|"calls"| LoginUC

    %% UseCases to Domain
    CreateAccountUC --> RepoInterfaces
    LoginUC --> RepoInterfaces
    FindAccountUC --> RepoInterfaces
    FindBalanceUC --> RepoInterfaces
    FindTransfersUC --> RepoInterfaces
    MakeTransferUC --> RepoInterfaces
    RepoInterfaces --> AccountEntity
    RepoInterfaces --> TransferEntity
    AccountEntity --> CommonTypes
    TransferEntity --> CommonTypes
    CommonTypes --> DomainErrors

    %% Domain to Infra DB
    RepoInterfaces -.-> AccountRepo
    RepoInterfaces -.-> TransferRepo
    AccountRepo --> DBConn
    TransferRepo --> DBConn
    DBConn --> PostgresDB

    %% Config & Bootstrapping
    Config --> Main
    Main --> Webserver
    Main --> DBConn
    Main --> AccountRepo
    Main --> TransferRepo
    Main --> CreateAccountUC
    Main --> LoginUC
    Main --> FindAccountUC
    Main --> FindBalanceUC
    Main --> FindTransfersUC
    Main --> MakeTransferUC

    %% Orchestration
    DockerCompose --> Main
    DockerCompose --> PostgresDB
    Dockerfile -.-> Main
    SwaggerSpec --> Webserver
    WaitScript --> DockerCompose
    Makefile --> Main

    %% Click Events
    click Main "https://github.com/lucassantoss1701/bank-api/blob/main/cmd/server/main.go"
    click Config "https://github.com/lucassantoss1701/bank-api/blob/main/configs/configs.go"
    click AccountEntity "https://github.com/lucassantoss1701/bank-api/blob/main/internal/entity/account.go"
    click TransferEntity "https://github.com/lucassantoss1701/bank-api/blob/main/internal/entity/transfer.go"
    click CommonTypes "https://github.com/lucassantoss1701/bank-api/blob/main/internal/entity/common.go"
    click DomainErrors "https://github.com/lucassantoss1701/bank-api/blob/main/internal/entity/error.go"
    click RepoInterfaces "https://github.com/lucassantoss1701/bank-api/blob/main/internal/entity/interface.go"
    click CreateAccountUC "https://github.com/lucassantoss1701/bank-api/blob/main/internal/usecase/create_account.go"
    click LoginUC "https://github.com/lucassantoss1701/bank-api/blob/main/internal/usecase/login.go"
    click FindAccountUC "https://github.com/lucassantoss1701/bank-api/blob/main/internal/usecase/find_account.go"
    click FindBalanceUC "https://github.com/lucassantoss1701/bank-api/blob/main/internal/usecase/find_balance_by_account.go"
    click FindTransfersUC "https://github.com/lucassantoss1701/bank-api/blob/main/internal/usecase/find_transfers_by_account.go"
    click MakeTransferUC "https://github.com/lucassantoss1701/bank-api/blob/main/internal/usecase/make_transfer.go"
    click DBConn "https://github.com/lucassantoss1701/bank-api/blob/main/internal/infra/database/connection/connection.go"
    click AccountRepo "https://github.com/lucassantoss1701/bank-api/blob/main/internal/infra/database/account_repository.go"
    click TransferRepo "https://github.com/lucassantoss1701/bank-api/blob/main/internal/infra/database/transfer_repository.go"
    click RepoUtils "https://github.com/lucassantoss1701/bank-api/blob/main/internal/infra/database/repository.go"
    click WebServerImpl "https://github.com/lucassantoss1701/bank-api/blob/main/internal/infra/web/webserver/webserver.go"
    click AccountRoutes "https://github.com/lucassantoss1701/bank-api/blob/main/internal/infra/web/webserver/routes/account_routes.go"
    click TransferRoutes "https://github.com/lucassantoss1701/bank-api/blob/main/internal/infra/web/webserver/routes/transfer_routes.go"
    click AuthMW "https://github.com/lucassantoss1701/bank-api/blob/main/internal/infra/web/webserver/middleware/auth.go"
    click LogMW "https://github.com/lucassantoss1701/bank-api/blob/main/internal/infra/web/webserver/middleware/logger.go"
    click AccountHandler "https://github.com/lucassantoss1701/bank-api/blob/main/internal/infra/web/account_handler.go"
    click TransferHandler "https://github.com/lucassantoss1701/bank-api/blob/main/internal/infra/web/transfer_handler.go"
    click Responses "https://github.com/lucassantoss1701/bank-api/blob/main/internal/infra/web/responses/responses.go"
    click SwaggerUI "https://github.com/lucassantoss1701/bank-api/blob/main/docs/swagger.yaml"
    click SwaggerSpec "https://github.com/lucassantoss1701/bank-api/blob/main/docs/swagger.json"
    click Dockerfile "https://github.com/lucassantoss1701/bank-api/tree/main/Dockerfile"
    click DockerCompose "https://github.com/lucassantoss1701/bank-api/blob/main/docker-compose.yaml"
    click WaitScript "https://github.com/lucassantoss1701/bank-api/blob/main/wait-for-services.sh"
    click Makefile "https://github.com/lucassantoss1701/bank-api/tree/main/makefile"

    %% Styles
    classDef web fill:#ADD8E6,stroke:#000
    classDef usecase fill:#90EE90,stroke:#000
    classDef domain fill:#FFA500,stroke:#000
    classDef infra fill:#DDA0DD,stroke:#000
    classDef db fill:#C0C0C0,stroke:#000
    classDef config fill:#FFDEAD,stroke:#000
    classDef docs fill:#F0E68C,stroke:#000
    classDef external fill:#FFFFFF,stroke:#000,stroke-dasharray: 5 5
```
