# thanipro/axum-rust-rest-api-template architecture

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

- Interactive diagram: https://gitdiagram.com/thanipro/axum-rust-rest-api-template
- Repository: https://github.com/thanipro/axum-rust-rest-api-template

## Overview

##### Project type and purpose
- This is a template for a RESTful API service written in Rust, built on the Axum web framework with SQLx as the database access layer.
- Its purpose is to provide a clean, SOA-style directory structure and boilerplate for building register, login (token issuance), and profile endpoints on top of a MySQL (or configurable) database.

##### File structure
- Top-level:
- .env / .env.example for environment configuration
- migrations/ for SQL migration scripts
- Cargo.toml/Cargo.lock for Rust dependencies
- src/main.rs to bootstrap the server
- src/ subdivides by layer:
- config/ – database initialization and parameter loading
- entity/ – domain entities mapping to database tables
- error/ – custom error types per layer
- handler/ – HTTP handlers (core of each route)
- middleware/ – request interceptors (e.g. JWT auth)
- repository/ – data access methods using SQLx
- response/ – unified API response wrapper
- routes/ – route definitions grouping paths to handlers
- service/ – business logic (token management, user operations)
- state/ – shared state (database pool, auth/token state)

##### README for additional insights
- Uses Axum and SQLx, follows a SOA pattern rather than monolithic main.rs
- Three basic endpoints: register, login, profile
- Database is MySQL by default; easily swapped out via config/database.rs and migrations.

a. Main components
- Clients (Postman, web app, mobile apps)
- HTTP server (Axum) with a router
- Middleware layer (authentication)
- Handlers (register_handler, auth_handler, profile_handler)
- Service layer (user_service, token_service)
- Repository layer (user_repository)
- Database (MySQL via SQLx connection pool)
- Config & State modules (parameter loader, database pool initializer)
- Migrations folder (external tool for schema setup)
b. Relationships and interactions
1. Client → HTTP request → Axum Router
2. Router dispatches to appropriate Handler
3. Handler invokes Middleware (e.g., validate JWT) if required
4. Handler calls into Service layer for business logic
5. Service uses Repository to read/write to Database
6. Repository executes SQLx queries via the shared Pool
7. Data flows back up: Repository → Service → Handler → Response to Client
c. Architectural patterns and principles
- Separation of Concerns: clear layering (API → Handler → Service → Repository → DB)
- Dependency Injection via shared State (database pool, auth/token state)
- DTOs isolate external API contracts from Entity models
- Centralized Error types and Response envelopes for consistent error handling
d. Key technologies and libraries
- Rust & Tokio for async runtime
- Axum for HTTP server and routing
- SQLx for compile-time-checked SQL queries and connection pooling
- dotenv or custom parameter loader for environment config
- async-trait for abstracting database backends

##### Detail
- Initialization sequence is visible: loading `.env` → building Config → establishing DB pool → launching Axum server with attached state.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Environment and Initialization
    EnvFiles[".env / .env.example"]:::config
    ConfigModule["Config Module\n(src/config)"]:::config
    StateModule["State Module\n(src/state)"]:::state
    Main["Axum Server\n(src/main.rs)"]:::server

    EnvFiles -->|"load parameters"| ConfigModule
    ConfigModule -->|"init DB pool & auth"| StateModule
    StateModule -->|"inject state"| Main

    %% Routing Layer
    subgraph "Routes Module" 
        direction TB
        RegisterRoute["register.rs"]:::routes
        AuthRoute["auth.rs"]:::routes
        ProfileRoute["profile.rs"]:::routes
        RootRoute["root.rs"]:::routes
    end
    Main -->|"mount routes"| RegisterRoute
    Main --> AuthRoute
    Main --> ProfileRoute
    Main --> RootRoute

    Router["Router"]:::api
    RegisterRoute --> Router
    AuthRoute --> Router
    ProfileRoute --> Router
    RootRoute --> Router

    %% Middleware Layer
    subgraph "Middleware Module" 
        direction TB
        AuthMW["auth.rs"]:::middleware
    end
    Router --> AuthMW

    %% Handler Layer
    subgraph "Handlers" 
        direction TB
        RegisterHandler["register_handler.rs"]:::handler
        AuthHandler["auth_handler.rs"]:::handler
        ProfileHandler["profile_handler.rs"]:::handler
    end
    Router --> RegisterHandler
    Router --> AuthHandler
    Router --> ProfileHandler
    AuthMW --> ProfileHandler

    %% Service Layer
    subgraph "Service Module" 
        direction TB
        UserService["user_service.rs"]:::service
        TokenService["token_service.rs"]:::service
    end
    RegisterHandler --> UserService
    AuthHandler --> TokenService
    ProfileHandler --> UserService

    %% Repository Layer
    subgraph "Repository Module"
        direction TB
        UserRepo["user_repository.rs"]:::repository
    end
    UserService --> UserRepo

    %% Data Layer
    Database[(MySQL Database)]:::database
    UserRepo -->|"SQLx queries"| Database
    ConfigModule --> Database

    %% Support Modules
    subgraph "DTO Module" 
        direction TB
        TokenDTO["token_dto.rs"]:::dto
        UserDTO["user_dto.rs"]:::dto
    end
    subgraph "Entity Module" 
        direction TB
        UserEntity["user.rs"]:::entity
    end
    subgraph "Error Module" 
        direction TB
        APIError["api_error.rs"]:::error
        DBError["db_error.rs"]:::error
        RequestError["request_error.rs"]:::error
        TokenError["token_error.rs"]:::error
        UserError["user_error.rs"]:::error
    end
    subgraph "Response Module"
        direction TB
        APIResponse["api_response.rs"]:::response
    end
    RegisterHandler --> TokenDTO
    RegisterHandler --> UserDTO
    UserRepo --> UserEntity
    RegisterHandler --> APIResponse
    UserService --> APIError

    %% Migrations
    Migrations["migrations/20230501172218_user.sql"]:::migrations
    Migrations --> Database

    %% Styles
    classDef config fill:#D6E9C6,stroke:#3C763D
    classDef state fill:#FCF8E3,stroke:#8A6D3B
    classDef server fill:#D9EDF7,stroke:#31708F
    classDef routes fill:#F2DEDE,stroke:#A94442
    classDef api fill:#FCF8E3,stroke:#8A6D3B
    classDef middleware fill:#F2DEDE,stroke:#A94442
    classDef handler fill:#D9EDF7,stroke:#31708F
    classDef service fill:#D6E9C6,stroke:#3C763D
    classDef repository fill:#F2DEDE,stroke:#A94442
    classDef database fill:#D9EDF7,stroke:#31708F,shape:cylinder
    classDef dto fill:#FCF8E3,stroke:#8A6D3B
    classDef entity fill:#D6E9C6,stroke:#3C763D
    classDef error fill:#F2DEDE,stroke:#A94442
    classDef response fill:#D9EDF7,stroke:#31708F
    classDef migrations fill:#FCF8E3,stroke:#8A6D3B

    %% Click Events
    click ConfigModule "https://github.com/thanipro/axum-rust-rest-api-template/blob/main/src/config/mod.rs"
    click ConfigModule "https://github.com/thanipro/axum-rust-rest-api-template/blob/main/src/config/database.rs"
    click ConfigModule "https://github.com/thanipro/axum-rust-rest-api-template/blob/main/src/config/parameter.rs"
    click StateModule "https://github.com/thanipro/axum-rust-rest-api-template/blob/main/src/state/mod.rs"
    click StateModule "https://github.com/thanipro/axum-rust-rest-api-template/blob/main/src/state/auth_state.rs"
    click StateModule "https://github.com/thanipro/axum-rust-rest-api-template/blob/main/src/state/token_state.rs"
    click StateModule "https://github.com/thanipro/axum-rust-rest-api-template/blob/main/src/state/user_state.rs"
    click TokenDTO "https://github.com/thanipro/axum-rust-rest-api-template/blob/main/src/dto/token_dto.rs"
    click UserDTO "https://github.com/thanipro/axum-rust-rest-api-template/blob/main/src/dto/user_dto.rs"
    click UserEntity "https://github.com/thanipro/axum-rust-rest-api-template/blob/main/src/entity/user.rs"
    click APIError "https://github.com/thanipro/axum-rust-rest-api-template/blob/main/src/error/api_error.rs"
    click DBError "https://github.com/thanipro/axum-rust-rest-api-template/blob/main/src/error/db_error.rs"
    click RequestError "https://github.com/thanipro/axum-rust-rest-api-template/blob/main/src/error/request_error.rs"
    click TokenError "https://github.com/thanipro/axum-rust-rest-api-template/blob/main/src/error/token_error.rs"
    click UserError "https://github.com/thanipro/axum-rust-rest-api-template/blob/main/src/error/user_error.rs"
    click RegisterHandler "https://github.com/thanipro/axum-rust-rest-api-template/blob/main/src/handler/register_handler.rs"
    click AuthHandler "https://github.com/thanipro/axum-rust-rest-api-template/blob/main/src/handler/auth_handler.rs"
    click ProfileHandler "https://github.com/thanipro/axum-rust-rest-api-template/blob/main/src/handler/profile_handler.rs"
    click AuthMW "https://github.com/thanipro/axum-rust-rest-api-template/blob/main/src/middleware/auth.rs"
    click UserRepo "https://github.com/thanipro/axum-rust-rest-api-template/blob/main/src/repository/user_repository.rs"
    click APIResponse "https://github.com/thanipro/axum-rust-rest-api-template/blob/main/src/response/api_response.rs"
    click RegisterRoute "https://github.com/thanipro/axum-rust-rest-api-template/blob/main/src/routes/register.rs"
    click AuthRoute "https://github.com/thanipro/axum-rust-rest-api-template/blob/main/src/routes/auth.rs"
    click ProfileRoute "https://github.com/thanipro/axum-rust-rest-api-template/blob/main/src/routes/profile.rs"
    click RootRoute "https://github.com/thanipro/axum-rust-rest-api-template/blob/main/src/routes/root.rs"
    click UserService "https://github.com/thanipro/axum-rust-rest-api-template/blob/main/src/service/user_service.rs"
    click TokenService "https://github.com/thanipro/axum-rust-rest-api-template/blob/main/src/service/token_service.rs"
    click Migrations "https://github.com/thanipro/axum-rust-rest-api-template/blob/main/migrations/20230501172218_user.sql"
```
