# dhvll/go-advance architecture

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

- Interactive diagram: https://gitdiagram.com/dhvll/go-advance
- Repository: https://github.com/dhvll/go-advance

## Overview

##### Project Type & Purpose
- Recognize that this is an advanced Golang project focusing on:
- API development (with endpoints for accounts, users, transfers)
- Database interaction (using migrations, SQL queries, and SQLC-generated code)
- Token-based authentication mechanisms (supporting both JWT and PASETO)
- Utility functions for configuration management, password handling, and currency operations
- The project is educational in nature, so the architecture emphasizes separation of concerns and clear modularity.

##### Main Components
- Client Interface (External or internal clients making API calls)
- API Server (Located in the api directory)
- Contains handlers (account.go, user.go, transfer.go), middleware (middleware.go), and tests.
- Handles HTTP requests and routes them to the appropriate business logic.
- Database Layer
- Migration Scripts (in db/migration) for initializing/updating the schema.
- Query Files (in db/query) that contain raw SQL scripts.
- SQLC-generated Code (in db/sqlc) acting as a data access layer (store, models, querier).
- A mock layer (db/mock) for testing database interactions.
- Token Management Module
- Implements token generation and validation using JWT and PASETO (in the token folder).
- Utility Package
- Provides configuration (util/config.go), currency conversion, password management (util/password.go), and randomness (util/random.go).
- Build & Deployment
- Makefile for build automation.
- GitHub workflows (.github/workflows/ci.yml) for continuous integration.
- Environment configurations (app.env, simplebank.sql for database seed/definitions).

##### Relationships & Interactions
- That the Client makes HTTP calls which reach the API Server.
- The API Server routes requests (using the middleware for authentication and validation) to specific endpoint handlers (for account, user, transfer operations).
- The handlers communicate with a database store that wraps interactions with the SQLC-generated modules.
- The Database, designed with clear migration scripts and query definitions, serves the persistent data needs.
- Token management is used by the API Server (particularly in middleware) to verify and issue authentication tokens.
- Utility functions are called by various modules (API, token, DB initialization) to manage configuration, security (password hashing), and other common tasks.

##### Architectural Patterns & Design Principles
- Emphasis on separation of concerns: API handling, database access, token management, and utility operations are kept in distinct modules.
- Use of automated database migrations and generated code (using SQLC) for robust database interfacing.
- Testing is integrated at multiple levels (with files ending in _test.go across several directories) to ensure code stability.
- The design supports high modularity which makes it easier to swap or upgrade parts (e.g., different token makers).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    CLIENT("Client Interface"):::client

    %% API Server Layer
    APISRV("API Server"):::api

    %% Token Management Module
    TOKEN("Token Management Module"):::token

    %% Utility Package
    UTIL("Utility Package"):::util

    %% Database Layer Subgraph
    subgraph "Database Layer"
        DB_MIG("Migrations"):::db
        DB_QUERY("Query Files"):::db
        DB_SQLC("SQLC-Generated Code"):::db
        DB_MOCK("DB Mock/Testing"):::db
    end

    %% Build & Deployment Subgraph
    subgraph "Build & Deployment"
        MAKEFILE("Make Automation (Makefile)"):::build
        CI("CI/CD Workflow (.github/workflows/ci.yml)"):::build
        ENV1("Environment Config (app.env)"):::build
        ENV2("Environment Config (simplebank.sql)"):::build
    end

    %% Relationships
    CLIENT -->|"HTTP Requests"| APISRV
    APISRV -->|"CallsSQLC"| DB_SQLC
    APISRV -->|"AuthCalls"| TOKEN
    APISRV -->|"UsesUtilities"| UTIL
    TOKEN -->|"UsesUtilities"| UTIL

    DB_MIG -->|"SetsUp"| DB_QUERY
    DB_QUERY -->|"FeedsInto"| DB_SQLC
    DB_SQLC -->|"TestedBy"| DB_MOCK

    %% Click Events
    click APISRV "https://github.com/dhvll/go-advance/tree/main/api/"
    click DB_MIG "https://github.com/dhvll/go-advance/tree/main/db/migration/"
    click DB_QUERY "https://github.com/dhvll/go-advance/tree/main/db/query/"
    click DB_SQLC "https://github.com/dhvll/go-advance/tree/main/db/sqlc/"
    click DB_MOCK "https://github.com/dhvll/go-advance/tree/main/db/mock/"
    click TOKEN "https://github.com/dhvll/go-advance/tree/main/token/"
    click UTIL "https://github.com/dhvll/go-advance/tree/main/util/"
    click MAKEFILE "https://github.com/dhvll/go-advance/tree/main/Makefile"
    click CI "https://github.com/dhvll/go-advance/blob/main/.github/workflows/ci.yml"
    click ENV1 "https://github.com/dhvll/go-advance/blob/main/app.env"
    click ENV2 "https://github.com/dhvll/go-advance/blob/main/simplebank.sql"

    %% Styles
    classDef client fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef api fill:#bbf,stroke:#333,stroke-width:2px;
    classDef token fill:#fbb,stroke:#333,stroke-width:2px;
    classDef util fill:#aaf,stroke:#333,stroke-width:2px;
    classDef db fill:#bfb,stroke:#333,stroke-width:2px;
    classDef build fill:#fdd,stroke:#333,stroke-width:2px;
```
