# codetheuri/tusk architecture

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

- Interactive diagram: https://gitdiagram.com/codetheuri/tusk
- Repository: https://github.com/codetheuri/tusk

## Overview

##### Project type and purpose
- This is a Go-based API starter template (“Tusk”) implementing a backend service with no frontend shipped.
- Purpose: Provide a clean-architecture foundation with modules (auth, todo), CLI tools (migrate, genmodule), middleware, logging, and database support to accelerate API development.

##### File structure
- Top-level:
- cmd/         → entrypoints for server (cmd/main.go), migration CLI (cmd/migrate), module generator CLI (cmd/genmodule)
- internal/    → core application code organized by layer and module
- pkg/         → shared utilities (auth token, errors, logger, mailer, middleware, pagination, validators, web helpers)
- config/, database/, docker-compose.yml, Dockerfile  → configuration and infrastructure
- internal/app:
- routers/     → HTTP router initialization (using chi)
- auth/        → auth handlers, services, repositories, models, JWT & Bcrypt flows
- todo/        → todo domain handlers, services, repositories, models
- module.go    → module registration interfaces
- internal/platform/database → GORM setup
- internal/bootstrap/app.go → app assembly, module registration, middleware wiring
- database/migrations & seeders → schema definitions and initial data
- pkg middleware & utils used across handlers and services

##### Key insights from README
- Clean Architecture layering: handlers → services → repositories → models
- Uses Go-Chi for routing, GORM for ORM and migrations
- JWT-based authentication, Bcrypt hashing
- CLI tools for migrations and scaffolding new modules
- Logging, validation, error handling, pagination, mailer all pluggable via pkg/

##### Detailed capture of essential elements
- Middleware chain wrapping handlers
- Interface boundaries: service interfaces and repository interfaces in modules
- Module generator CLI interacting with the file system to scaffold new code directories

## Diagram (Mermaid)

```mermaid
flowchart TB
    Client["Client (e.g., Postman)"]:::external
    Client --> HTTPServer

    HTTPServer["HTTP Server<br/>(cmd/main.go)"]:::server
    click HTTPServer "https://github.com/codetheuri/tusk/blob/main/cmd/main.go"
    HTTPServer --> ConfigLoader
    HTTPServer --> Bootstrap

    ConfigLoader["Configuration Loader<br/>(config/config.go)"]:::util
    click ConfigLoader "https://github.com/codetheuri/tusk/blob/main/config/config.go"

    Bootstrap["Application Bootstrap & Module Registration<br/>(internal/bootstrap/app.go)"]:::util
    click Bootstrap "https://github.com/codetheuri/tusk/blob/main/internal/bootstrap/app.go"
    Bootstrap --> Router
    Bootstrap --> GORMSetup

    GORMSetup["GORM Database Setup<br/>(internal/platform/database/gorm.go)"]:::util
    click GORMSetup "https://github.com/codetheuri/tusk/blob/main/internal/platform/database/gorm.go"
    GORMSetup --> DB

    Router["Router & Middleware<br/>(internal/app/routers/router.go)"]:::router
    click Router "https://github.com/codetheuri/tusk/blob/main/internal/app/routers/router.go"

    subgraph "Auth Module" 
        direction TB
        AuthHandler["Auth Handlers"]:::module
        click AuthHandler "https://github.com/codetheuri/tusk/blob/main/internal/app/auth/handlers/handler.go"
        AuthService["Auth Services"]:::module
        click AuthService "https://github.com/codetheuri/tusk/blob/main/internal/app/auth/services/service.go"
        AuthRepo["Auth Repositories"]:::module
        click AuthRepo "https://github.com/codetheuri/tusk/blob/main/internal/app/auth/repositories/repository.go"
    end

    subgraph "Todo Module"
        direction TB
        TodoHandler["Todo Handlers"]:::module
        click TodoHandler "https://github.com/codetheuri/tusk/blob/main/internal/app/todo/handlers/todo.go"
        TodoService["Todo Services"]:::module
        click TodoService "https://github.com/codetheuri/tusk/blob/main/internal/app/todo/services/todo.go"
        TodoRepo["Todo Repositories"]:::module
        click TodoRepo "https://github.com/codetheuri/tusk/blob/main/internal/app/todo/repositories/todo.go"
    end

    Router --> AuthHandler
    AuthHandler --> AuthService
    AuthService --> AuthRepo
    AuthRepo --> DB

    Router --> TodoHandler
    TodoHandler --> TodoService
    TodoService --> TodoRepo
    TodoRepo --> DB

    DB["Database (PostgreSQL/MySQL)"]:::db

    subgraph "CLI Tools"
        direction TB
        MigrateCLI["Migrate CLI Tool"]:::cli
        click MigrateCLI "https://github.com/codetheuri/tusk/blob/main/cmd/migrate/main.go"
        GenModuleCLI["Module Generator CLI Tool"]:::cli
        click GenModuleCLI "https://github.com/codetheuri/tusk/blob/main/cmd/genmodule/main.go"
        Migrations["Database Migrations"]:::cli
        click Migrations "https://github.com/codetheuri/tusk/tree/main/database/migrations/"
        Seeders["Database Seeders"]:::cli
        click Seeders "https://github.com/codetheuri/tusk/tree/main/database/seeders/"
    end

    MigrateCLI --> Migrations
    MigrateCLI --> Seeders

    subgraph "Shared Utilities"
        direction TB
        Logger["Logger Utility"]:::util
        click Logger "https://github.com/codetheuri/tusk/blob/main/pkg/logger/logger.go"
        Errors["Error Handling"]:::util
        click Errors "https://github.com/codetheuri/tusk/blob/main/pkg/errors/errors.go"
        Mailer["Mailer Utility"]:::util
        click Mailer "https://github.com/codetheuri/tusk/blob/main/pkg/mailer/mailer.go"
        Pagination["Pagination Utility"]:::util
        click Pagination "https://github.com/codetheuri/tusk/blob/main/pkg/pagination/pagination.go"
        Validators["Validators"]:::util
        click Validators "https://github.com/codetheuri/tusk/blob/main/pkg/validators/validator.go"
        WebHelpers["Web Helpers"]:::util
        click WebHelpers "https://github.com/codetheuri/tusk/blob/main/pkg/web/web.go"
        AuthToken["Auth Token Interfaces"]:::util
        click AuthToken "https://github.com/codetheuri/tusk/blob/main/pkg/auth/token/interface.go"
        Middleware["Middleware Components"]:::util
        click Middleware "https://github.com/codetheuri/tusk/blob/main/pkg/middleware/auth_middleware.go"
    end

    AuthHandler --> Logger
    AuthHandler --> Errors
    AuthService --> Validators
    AuthService --> AuthToken
    AuthService --> Mailer
    TodoHandler --> Logger
    TodoHandler --> Errors
    TodoService --> Pagination
    TodoService --> Validators

    classDef server fill:#EEEAFD,stroke:#7266BA,color:#333;
    classDef router fill:#FDF6E3,stroke:#FFD700,color:#333;
    classDef module fill:#E3F6FD,stroke:#00A5CF,color:#333;
    classDef util fill:#E6F4EA,stroke:#00A65A,color:#333;
    classDef cli fill:#F2F2F2,stroke:#A6A6A6,color:#333;
    classDef db fill:#FDE6E0,stroke:#F04E23,color:#333;
    classDef external fill:#FFFFFF,stroke:#999999,color:#333;
    classDef utilgroup fill:none,stroke:none;color:#333;
```
