# maxcountryman/axum-login architecture

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

- Interactive diagram: https://gitdiagram.com/maxcountryman/axum-login
- Repository: https://github.com/maxcountryman/axum-login

## Overview

##### Project type and purpose
- This is primarily a **library crate** (`axum-login/`) exposing middleware, extractors, and traits to handle user identification, authentication, and authorization in Axum-based servers.
- The `examples/` directory holds **reference applications** (full-stack web servers) that use the crate to demonstrate common use cases (OAuth2, permissions, SQLite backends, etc.).

##### File structure
- **Top-level**
- `Cargo.toml`, `src/` (lib code), `tests/` (integration tests)
- `.github/workflows/rust.yml` for CI
- **Library modules** in `axum-login/src/`:
- `backend.rs` – trait definitions (`AuthnBackend`, `AuthzBackend`)
- `extract.rs` – extractors (`AuthSession`)
- `middleware.rs` – middleware wrappers (`login_required`, `permission_required`)
- `service.rs` – high-level service interfaces
- `session.rs` – session management (powered by `tower-sessions`)
- **Examples** (each a standalone binary) under `examples/…`:
- Config (`.env.example`), database migrations
- `src/main.rs`, plus modules for users, web (routes, handlers, template rendering)

##### Key insights from README
- The library is built as **Tower middleware** for **Axum**.
- It supports **pluggable backends** (`AuthnBackend` for authentication, `AuthzBackend` for authorization) and **session stores** via `tower-sessions`.
- Examples illustrate integration with SQL (SQLite, Postgres), OAuth2, and custom permission schemes.

##### Main components
a. **Client** (Web browser or API consumer)
b. **HTTP Server** (Axum)
c. **Middleware Layer** (axum-login)
- `AuthSession` extractor
- `login_required` / `permission_required`
d. **Authentication Backend** (impl of `AuthnBackend`)
e. **Authorization Backend** (impl of `AuthzBackend`)
f. **Session Store** (`tower-sessions`: cookie store, Redis, etc.)
g. **Data Store** (SQL database—SQLite/Postgres—or external directory)
h. **Handler Logic** (business-specific routes / template rendering)
i. **External OAuth Provider** (only in oauth2 example)

##### Relationships & data flows
1. Client → HTTP Request → Axum Router
2. Axum passes request into **axum-login middleware**
- Load session from cookie or store
- If protected, enforce login or permission checks via extractor
3. Middleware invokes **AuthnBackend** to validate user credentials or session
4. On success, **AuthSession** injected into Handler
5. Handler may query the **Data Store** (users table, groups, permissions) via async DB client
6. On routes using OAuth, Handler redirects to external provider, exchanges code, calls **AuthnBackend**
7. Responses flow back through middleware → Axum → Client

##### Architectural patterns & principles
- **Middleware pipeline** (layered request processing)
- **Trait-based abstraction** for backends (pluggable implementations)
- **Separation of concerns**: session management vs. authentication logic vs. handler code
- **Dependency injection**: backends passed into the Router at startup

##### Technologies & frameworks
- Rust, Tokio (async)
- Axum (web framework)
- Tower & Tower-Sessions (middleware & session management)
- SQLx or Diesel (DB access in examples)
- Askama / Handlebars / Tera (template engines in examples)

##### Essential elements to capture
- The flow of an HTTP request through Axum → axum-login middleware → Handler → DB
- How and where session state is stored/retrieved
- Points of extension: where a user plugs in their own `AuthnBackend` / `AuthzBackend`

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Client["Web Browser / API Client"]:::external

    %% Example App - multi-auth
    subgraph "Example App: multi-auth" 
        direction TB
        MA_Main["HTTP Server Setup\n(main.rs)"]:::example
        MA_App["Router Configuration\n(app.rs)"]:::example
        MA_AuthRoutes["Auth Routes Handler\n(auth.rs)"]:::example
        MA_Protected["Protected Routes Handler\n(protected.rs)"]:::example
        MA_OAuth["OAuth Handler Logic\n(oauth.rs)"]:::example
        MA_Users["User Model & Data Access\n(users.rs)"]:::example
        MA_Migrations["SQL Migrations"]:::example
    end

    %% Core Library - axum-login crate
    subgraph "Core Library: axum-login crate"
        direction TB
        LIB_Entry["lib.rs\n(Core Entry)"]:::lib
        LIB_Backend["AuthnBackend & AuthzBackend Traits\n(backend.rs)"]:::lib
        LIB_Extract["AuthSession Extractor\n(extract.rs)"]:::lib
        LIB_Middleware["Middleware Wrappers\n(middleware.rs)"]:::lib
        LIB_Session["Session Management\n(session.rs)"]:::lib
        LIB_Service["High-Level Service Interfaces\n(service.rs)"]:::lib
        LIB_Tests["Integration Tests\n(integration-test.rs)"]:::lib
    end

    %% External Services
    subgraph "External Services"
        direction TB
        SessionStore["Session Store\n(tower-sessions)"]:::external
        Database["SQL Database\n(SQLite / Postgres)"]:::external
        OAuthProvider["External OAuth Provider"]:::external
    end

    %% Flow connections
    Client -->|HTTP Request| MA_Main
    MA_Main --> MA_App
    MA_App -->|Applies Middleware| LIB_Middleware
    LIB_Middleware --> LIB_Extract
    LIB_Middleware --> LIB_Backend
    LIB_Extract -->|Injects AuthSession| MA_AuthRoutes
    MA_AuthRoutes -->|Calls Backend| LIB_Backend
    LIB_Backend --> SessionStore
    SessionStore -->|Session Data| LIB_Session
    LIB_Backend --> Database
    MA_Protected --> Database
    MA_OAuth --> OAuthProvider
    OAuthProvider --> LIB_Backend
    MA_OAuth -->|On Success| MA_AuthRoutes
    MA_Users --> Database

    %% Click Events - Example App
    click MA_Main "https://github.com/maxcountryman/axum-login/blob/main/examples/multi-auth/src/main.rs"
    click MA_App "https://github.com/maxcountryman/axum-login/blob/main/examples/multi-auth/src/web/app.rs"
    click MA_AuthRoutes "https://github.com/maxcountryman/axum-login/blob/main/examples/multi-auth/src/web/auth.rs"
    click MA_Protected "https://github.com/maxcountryman/axum-login/blob/main/examples/multi-auth/src/web/protected.rs"
    click MA_OAuth "https://github.com/maxcountryman/axum-login/blob/main/examples/multi-auth/src/web/oauth.rs"
    click MA_Users "https://github.com/maxcountryman/axum-login/blob/main/examples/multi-auth/src/users.rs"
    click MA_Migrations "https://github.com/maxcountryman/axum-login/blob/main/examples/multi-auth/migrations/20231108213118_init.sql"

    %% Click Events - Core Library
    click LIB_Entry "https://github.com/maxcountryman/axum-login/blob/main/axum-login/src/lib.rs"
    click LIB_Backend "https://github.com/maxcountryman/axum-login/blob/main/axum-login/src/backend.rs"
    click LIB_Extract "https://github.com/maxcountryman/axum-login/blob/main/axum-login/src/extract.rs"
    click LIB_Middleware "https://github.com/maxcountryman/axum-login/blob/main/axum-login/src/middleware.rs"
    click LIB_Session "https://github.com/maxcountryman/axum-login/blob/main/axum-login/src/session.rs"
    click LIB_Service "https://github.com/maxcountryman/axum-login/blob/main/axum-login/src/service.rs"
    click LIB_Tests "https://github.com/maxcountryman/axum-login/blob/main/axum-login/tests/integration-test.rs"

    %% Styles
    classDef lib fill:#D6EAF8,stroke:#21618C,color:#1B4F72;
    classDef example fill:#D5F5E3,stroke:#229954,color:#196F3D;
    classDef external fill:#FADBD8,stroke:#922B21,color:#641E16;
```
