# ridos/todo-app architecture

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

- Interactive diagram: https://gitdiagram.com/ridos/todo-app
- Repository: https://github.com/ridos/todo-app

## Overview

##### Project Type and Purpose
- This is a monolithic RESTful API server written in Go that implements a Todo application. It follows a layered (“Clean”) architecture separating transport (HTTP), business logic, and data access. It uses Postgres for persistence and Docker for local development.

##### High-Level Components
a. API Server
- Entry point: `cmd/main.go` → loads config (`configs/config.yml` + `.env`), initializes router and middleware (`server.go`), and starts the HTTP listener.
b. Handler Layer (Transport)
- Directory: `pkg/handlers/`
- Files: `auth.go`, `item.go`, `list.go`, `middleware.go`, `response.go`
- Responsibilities: parse HTTP requests, validate input, enforce auth middleware, format HTTP responses.
c. Service Layer (Business Logic)
- Directory: `pkg/service/`
- Files: `auth.go`, `todo_item.go`, `todo_list.go`, `service.go`
- Responsibilities: orchestrate use cases (e.g., create list, add item), apply domain rules, call repository.
d. Repository Layer (Data Access)
- Directory: `pkg/repository/`
- Files: `auth_postgres.go`, `todo_item_postgres.go`, `todo_list_postgres.go`, `postgres.go`, `repository.go`
- Responsibilities: connect to Postgres, run SQL queries, map rows to domain models.
e. Database
- Postgres container (instructions in README)
- Migrations in `schema/1.sql`, `schema/2.sql`
f. Configuration & Deployment
- Config in `configs/config.yml` and `.env`
- Docker for Postgres setup
- Go modules in `go.mod`/`go.sum`

##### Component Interactions & Data Flow
1. Client (e.g., browser, Postman) → HTTP Request
2. Router & Middleware (`server.go` + `pkg/handlers/middleware.go`)
3. Handler (`pkg/handlers/*.go`)
4. Service (`pkg/service/*.go`)
5. Repository (`pkg/repository/*.go`)
6. Postgres DB (`schema/*.sql`)
7. Back up chain: DB → Repo → Service → Handler → Client response

##### Architectual Patterns & Principles
- Layered (Clean) Architecture: decouple transport, business, data layers
- Dependency Injection: pass repository interfaces into services
- Single Responsibility: each package/file has a clear role
- Configuration-driven: externalize DB credentials and ports

##### Detail Orientation
- Environment variables (.env) feeding into config loader.
- Docker container boundary around Postgres.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    Client["Client (Browser/Postman)"]:::client

    %% API Server Layer
    HTTP["HTTP Server\n(cmd/main.go, server.go)"]:::service

    %% Handler Layer
    Handlers["Handlers\n(pkg/handlers/*.go)"]:::service

    %% Service Layer
    Services["Services\n(pkg/service/*.go)"]:::service

    %% Repository Layer
    Repos["Repositories\n(pkg/repository/*.go)"]:::service

    %% Database Layer
    DB["Postgres DB\n(schema/*.sql)"]:::db

    %% Configuration & Migrations
    subgraph "Configuration & Migrations"
        Config["Config\n(configs/config.yml, .env)"]:::config
        Migrations["Migrations\n(schema/*.sql)"]:::config
        GoMod["Go Modules\n(go.mod, go.sum)"]:::config
    end

    %% Data Flow
    Client -->|"HTTP GET /lists"| HTTP
    HTTP -->|"parse request\n& validate"| Handlers
    Handlers -->|"business logic calls"| Services
    Services -->|"data access calls"| Repos
    Repos -->|"SQL SELECT/INSERT"| DB
    DB -->|"rows mapped"| Repos
    Repos -->|"results"| Services
    Services -->|"response data"| Handlers
    Handlers -->|"HTTP response"| Client

    %% Config relations
    Config -->|"load config"| HTTP
    GoMod -->|"dependency setup"| HTTP
    Migrations -->|"init schema"| DB

    %% Click Events - API Server
    click HTTP "https://github.com/ridos/todo-app/blob/master/cmd/main.go"
    click HTTP "https://github.com/ridos/todo-app/blob/master/server.go"

    %% Click Events - Handlers
    click Handlers "https://github.com/ridos/todo-app/blob/master/pkg/handlers/auth.go"
    click Handlers "https://github.com/ridos/todo-app/blob/master/pkg/handlers/handler.go"
    click Handlers "https://github.com/ridos/todo-app/blob/master/pkg/handlers/item.go"
    click Handlers "https://github.com/ridos/todo-app/blob/master/pkg/handlers/list.go"
    click Handlers "https://github.com/ridos/todo-app/blob/master/pkg/handlers/middleware.go"
    click Handlers "https://github.com/ridos/todo-app/blob/master/pkg/handlers/response.go"

    %% Click Events - Services
    click Services "https://github.com/ridos/todo-app/blob/master/pkg/service/auth.go"
    click Services "https://github.com/ridos/todo-app/blob/master/pkg/service/service.go"
    click Services "https://github.com/ridos/todo-app/blob/master/pkg/service/todo_item.go"
    click Services "https://github.com/ridos/todo-app/blob/master/pkg/service/todo_list.go"

    %% Click Events - Repositories
    click Repos "https://github.com/ridos/todo-app/blob/master/pkg/repository/auth_postgres.go"
    click Repos "https://github.com/ridos/todo-app/blob/master/pkg/repository/todo_item_postgres.go"
    click Repos "https://github.com/ridos/todo-app/blob/master/pkg/repository/todo_list_postgres.go"
    click Repos "https://github.com/ridos/todo-app/blob/master/pkg/repository/postgres.go"
    click Repos "https://github.com/ridos/todo-app/blob/master/pkg/repository/repository.go"

    %% Click Events - Configuration & Migrations
    click Config "https://github.com/ridos/todo-app/blob/master/configs/config.yml"
    click Config "https://github.com/ridos/todo-app/blob/master/.env"
    click Migrations "https://github.com/ridos/todo-app/blob/master/schema/1.sql"
    click Migrations "https://github.com/ridos/todo-app/blob/master/schema/2.sql"
    click GoMod "https://github.com/ridos/todo-app/blob/master/go.mod"
    click GoMod "https://github.com/ridos/todo-app/blob/master/go.sum"

    %% Styles
    classDef client fill:#d0e1f9,stroke:#333,color:#000;
    classDef service fill:#a2d2ff,stroke:#333,color:#000;
    classDef db fill:#b7e4c7,stroke:#333,color:#000;
    classDef config fill:#e5e5e5,stroke:#333,color:#000;
```
