# yuxuetr/axum-template architecture

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

- Interactive diagram: https://gitdiagram.com/yuxuetr/axum-template
- Repository: https://github.com/yuxuetr/axum-template

## Overview

##### Project type and purpose
- This is a Rust-based backend web service template built on the Axum framework.
- It exposes HTTP APIs, implements authentication (JWT with Ed25519), and provides user management via a Postgres database (using SQLx).
- The project uses a Nest.js–style organization: `common` utilities and individual business `modules` (`auth`, `users`), plus automated key generation, migrations, and REST-client fixtures.

##### File structure
- Top-level:
- `.github/workflows/build.yml` – CI pipeline.
- `app.yaml` – deployment config (e.g., App Engine).
- `build.rs` – build script that generates Ed25519 keys into `fixtures`.
- `docs/`, `fixtures/`, `migrations/`, `rest_client/` – supporting artifacts.
- `src/` – source code subdivided into:
– `common/` – cross-cutting services (config loader, error definitions, auth helpers).
– `modules/` – feature modules.
· `auth/` – login, signup endpoints, JWT middleware.
· `users/` – CRUD user management.
– `lib.rs` – root router and global state initialization (config + database pool).
– `main.rs` – server entry point.

##### README for additional insights
- Auth token uses Ed25519; keypairs auto-generated by `build.rs`.
- Global state bundles config + SQLx pool to be injected into service functions.
- Testing strategy: unit and integration tests in each module’s `tests.rs`.
- CI uses GitHub Actions; strict linting via `pre-commit` and `cargo-deny`.

a. Main components
1. API Gateway (Axum HTTP server)
2. Common Utilities (config loader, error handler, JWT helper)
3. Auth Module (handlers, services, middleware)
4. Users Module (handlers, services, entity definitions)
5. Global State (application state containing config & database connection pool)
6. Postgres Database
7. Build Script (`build.rs`) & Fixtures (keypair generation)
8. External CI/CD (GitHub Actions)
9. REST Client Tests (VS Code REST client)
b. Relationships & interactions
- Client → Axum HTTP Server (`main.rs`)
- HTTP Server routes → Module routers (registered in `lib.rs`)
- Handler functions call module Services (injected with &AppState)
- Services use SQLx via AppState.pool → Postgres
- Auth middleware validates JWT using public key from fixtures
- build.rs → generates keypair in fixtures before compile
- GitHub Actions → `cargo build`, `cargo test`, `cargo deny`
- REST client files hit HTTP endpoints as part of testing
c. Architectural patterns & principles
- Layered architecture: HTTP layer (handlers/middleware) → business logic (services) → data access (SQLx/entities).
- Modular organization: separate folders per business domain.
- Dependency injection via global AppState.
- Code generation (keys) at build time.
- Migration folder follows SQLx conventions.
d. Key technologies
- Rust, Axum, Tower Middleware
- SQLx + Postgres
- JWT-Ed25519 (via `jwt-simple`)
- GitHub Actions, pre-commit, cargo-deny

##### Key recommendations
- Migration folder as part of your “Database” component or as a deployment artifact.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    Client["Client"]:::external

    %% Build-time Artifacts
    subgraph "Build-time Artifacts"
        BuildScript["build.rs"]:::build
        Fixtures["Fixtures"]:::build
        MigrationsFolder["migrations/"]:::build
    end

    %% API Server
    subgraph "API Server"
        Main["main.rs"]:::runtime
        Lib["lib.rs"]:::runtime
        AppState["AppState"]:::runtime
    end

    %% Common Utilities
    subgraph "Common Utilities"
        Config["config.rs"]:::runtime
        Errors["errors.rs"]:::runtime
        AuthHelper["auth.rs"]:::runtime
        CommonMod["mod.rs"]:::runtime
    end

    %% Auth Module
    subgraph "Auth Module"
        AuthMod["mod.rs"]:::runtime
        AuthHandlers["handlers.rs"]:::runtime
        AuthServices["services.rs"]:::runtime
        AuthMiddleware["middleware.rs"]:::runtime
        AuthDTO["dto.rs"]:::runtime
        AuthTests["tests.rs"]:::runtime
    end

    %% Users Module
    subgraph "Users Module"
        UsersMod["mod.rs"]:::runtime
        UserHandlers["handlers.rs"]:::runtime
        UserServices["services.rs"]:::runtime
        UserDTO["dto.rs"]:::runtime
        UserEntity["entity.rs"]:::runtime
        UserTests["tests.rs"]:::runtime
    end

    %% Database
    Postgres[(Postgres Database)]:::runtime
    Migrations["migrations"]:::build

    %% External Integrations
    subgraph "External"
        CICD["GitHub Actions"]:::external
        RESTTests["REST Client Tests"]:::external
    end

    %% Relationships
    Client -->|"HTTP Request"| Main
    Main -->|calls| Lib
    Lib -->|initializes| AppState
    Lib -->|registers routers| AuthMod
    Lib -->|registers routers| UsersMod

    Main -->|load keys| Fixtures
    BuildScript -->|generates keys| Fixtures

    Main -->|run migrations| MigrationsFolder
    AppState -->|provides pool| Postgres

    AuthMod -->|uses| Config
    AuthMod -->|handles errors via| Errors
    AuthMod -->|validates JWT via| AuthHelper
    AuthHandlers -->|injects| AppState
    AuthServices -->|executes SQL| Postgres
    AuthMiddleware -->|verifies JWT| Fixtures

    UsersMod -->|uses| Config
    UsersMod -->|handles errors via| Errors
    UserHandlers -->|injects| AppState
    UserServices -->|executes SQL| Postgres

    CICD -->|runs| BuildScript
    CICD -->|runs| Tests
    RESTTests -->|sends requests to| Main

    %% Click Events
    click Main "https://github.com/yuxuetr/axum-template/blob/main/src/main.rs"
    click Lib "https://github.com/yuxuetr/axum-template/blob/main/src/lib.rs"
    click AppState "https://github.com/yuxuetr/axum-template/blob/main/src/lib.rs"
    click Config "https://github.com/yuxuetr/axum-template/blob/main/src/common/config.rs"
    click Errors "https://github.com/yuxuetr/axum-template/blob/main/src/common/errors.rs"
    click AuthHelper "https://github.com/yuxuetr/axum-template/blob/main/src/common/auth.rs"
    click CommonMod "https://github.com/yuxuetr/axum-template/blob/main/src/common/mod.rs"
    click AuthMod "https://github.com/yuxuetr/axum-template/blob/main/src/modules/auth/mod.rs"
    click AuthHandlers "https://github.com/yuxuetr/axum-template/blob/main/src/modules/auth/handlers.rs"
    click AuthServices "https://github.com/yuxuetr/axum-template/blob/main/src/modules/auth/services.rs"
    click AuthMiddleware "https://github.com/yuxuetr/axum-template/blob/main/src/modules/auth/middleware.rs"
    click AuthDTO "https://github.com/yuxuetr/axum-template/blob/main/src/modules/auth/dto.rs"
    click AuthTests "https://github.com/yuxuetr/axum-template/blob/main/src/modules/auth/tests.rs"
    click UsersMod "https://github.com/yuxuetr/axum-template/blob/main/src/modules/users/mod.rs"
    click UserHandlers "https://github.com/yuxuetr/axum-template/blob/main/src/modules/users/handlers.rs"
    click UserServices "https://github.com/yuxuetr/axum-template/blob/main/src/modules/users/services.rs"
    click UserDTO "https://github.com/yuxuetr/axum-template/blob/main/src/modules/users/dto.rs"
    click UserEntity "https://github.com/yuxuetr/axum-template/blob/main/src/modules/users/entity.rs"
    click UserTests "https://github.com/yuxuetr/axum-template/blob/main/src/modules/users/tests.rs"
    click BuildScript "https://github.com/yuxuetr/axum-template/blob/main/build.rs"
    click Fixtures "https://github.com/yuxuetr/axum-template/tree/main/fixtures/"
    click MigrationsFolder "https://github.com/yuxuetr/axum-template/tree/main/migrations/"
    click CICD "https://github.com/yuxuetr/axum-template/blob/main/.github/workflows/build.yml"
    click RESTTests "https://github.com/yuxuetr/axum-template/tree/main/rest_client/"

    %% Styles
    classDef runtime fill:#E0F7FA,stroke:#0288D1,color:#000
    classDef build fill:#E8F5E9,stroke:#388E3C,color:#000
    classDef external fill:#FFF3E0,stroke:#F57C00,color:#000
```
