# vapor/fluent architecture

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

- Interactive diagram: https://gitdiagram.com/vapor/fluent
- Repository: https://github.com/vapor/fluent

## Overview

##### Project type and purpose
- This is an open-source Swift Package named “Fluent” (Package.swift at root).
- Purpose: provide a bridge between Vapor’s application lifecycle and FluentKit’s database abstraction, plus helpers for authentication, pagination, sessions, caching, and concurrency.

##### File structure
- Top-level files/directories:
- .github/             → CI workflows, code owners, contribution guidelines
- Package.swift        → Swift Package manifest (defines targets, dependencies)
- .spi.yml             → Swift Package Index configuration
- Sources/Fluent/      → Main library code
- ├─ Concurrency/    → Async/await extensions for FluentKit & Vapor providers
- ├─ Docs.docc/      → Documentation bundles for Swift-DocC
- ├─ Fluent+*.swift  → Extension files adding caching, history, pagination, sessions
- └─ FluentProvider.swift, MigrateCommand.swift, etc.
- Tests/FluentTests/   → Unit tests for each feature (cache, credentials, pagination, etc.)
- No frontend or backend sub-apps here; this is purely a library module.

##### README for additional insights
- It ties FluentKit into the Vapor app lifecycle.
- It provides model authentication helpers.
- References Vapor 4, Swift 5.8+; integration with FluentKit, Vapor’s authentication APIs.

##### Main components and their relationships
A. Vapor Application (host)
– Application lifecycle manages providers, commands, middleware, routing.
B. Fluent Package (integration layer)
– FluentProvider: registers database services on Application
– MigrateCommand: database migration CLI
– Model authentication extensions: ModelAuthenticatable, CredentialsAuthenticatable, TokenAuthenticatable
– Extensions: Fluent+Cache, Fluent+History, Fluent+Paginate, Fluent+Sessions
– Concurrency wrappers: async/await entry points for all major APIs
C. FluentKit (external dependency)
– Core database abstraction: QueryBuilder, Model, Schema
D. Database Drivers (outside this package)
– e.g. PostgreSQL, MySQL – actual connections and SQL dialects
E. Developer’s Models & Repositories
– User-defined structs/classes conforming to FluentKit’s Model protocols
F. Tests
– Unit tests targeting each extension to verify behavior

Interactions:
- Vapor App → registers FluentProvider
- FluentProvider → hooks into FluentKit to initialize Database pools
- Application CLI → exposes MigrateCommand
- Developer Models → use FluentKit’s query API via FluentProvider’s registered database
- Auth middleware → uses ModelAuthenticatable extensions
- Concurrency wrappers → enable async/await calls to database
- FluentKit → communicates with Database Driver → actual DB

##### Architectural patterns and design principles
- Provider pattern: FluentProvider conforms to Vapor’s Provider protocol
- Extension modularity: each feature (cache, history, pagination, sessions) lives in its own file/namespace
- Async/await wrappers: thin concurrency layer over callback-based APIs
- Separation of concerns: integration layer vs core database abstraction vs drivers vs application code
- Test-driven design: dedicated test target mirrors each extension module

##### Diagramming recommendations
- Rounded rectangle for “Vapor Application”
- Application host (blue)
- Integration library (green)
- Core abstraction (orange)
- External systems (gray)
- Tests (purple)
- Initialization flow: Application → FluentProvider → FluentKit
- Data flow: Models ↔ Query API ↔ Database
- Command invocation: CLI → MigrateCommand
- Async calls: concurrency wrappers → underlying APIs
- Labels:
- Protocols/interfaces (ModelAuthenticatable, QueryBuilder, etc.)

##### Putting it all together
- FluentProvider
- MigrateCommand
- Extensions (Cache, History, Paginate, Sessions)
- Concurrency
- Under “Fluent Package,” point to “FluentKit” as a dependency
- Off to one side, show “Developer Models & Repositories” calling into “FluentPackage → FluentKit”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Host application
    VaporApp["Vapor 4 Application"]:::host

    %% Package manifest
    PS["Package.swift"]:::integration
    click PS "https://github.com/vapor/fluent/blob/main/Package.swift"

    %% Fluent Package
    subgraph "Fluent Package"
        direction TB
        FP["FluentProvider"]:::integration
        MC["MigrateCommand"]:::integration
        MA["ModelAuthenticatable"]:::integration
        CA["CredentialsAuthenticatable"]:::integration
        TA["TokenAuthenticatable"]:::integration
        Cache["Fluent+Cache"]:::integration
        History["Fluent+History"]:::integration
        Paginate["Fluent+Paginate"]:::integration
        Sessions["Fluent+Sessions"]:::integration
        subgraph "Concurrency Wrappers"
            direction TB
            CW["Concurrency Wrappers"]:::integration
        end
        Exports["Exports.swift"]:::integration
        PageLimit["PageLimit.swift"]:::integration
        Docs["Docs.docc"]:::integration
    end

    %% Core abstraction
    FK["FluentKit"]:::core

    %% External systems
    DD["Database Drivers"]:::external
    DB[(Database)]:::external

    %% Developer code
    DM["Developer Models & Repositories"]:::dev

    %% Tests
    Tests["Tests/FluentTests"]:::tests

    %% Relationships
    VaporApp --> PS
    VaporApp --> FP
    VaporApp --> MC
    PS --> FP
    PS --> MC
    FP --> FK
    MC --> FK
    FK --> DD
    DD --> DB
    DM -.-> FK
    DM -.-> FP
    Tests --> Cache
    Tests --> MA
    Tests --> CA
    Tests --> TA
    Tests --> Paginate
    Tests --> History
    Tests --> Sessions

    %% Click Events
    click FP "https://github.com/vapor/fluent/blob/main/Sources/Fluent/FluentProvider.swift"
    click MC "https://github.com/vapor/fluent/blob/main/Sources/Fluent/MigrateCommand.swift"
    click MA "https://github.com/vapor/fluent/blob/main/Sources/Fluent/ModelAuthenticatable.swift"
    click CA "https://github.com/vapor/fluent/blob/main/Sources/Fluent/ModelCredentialsAuthenticatable.swift"
    click TA "https://github.com/vapor/fluent/blob/main/Sources/Fluent/ModelTokenAuthenticatable.swift"
    click Cache "https://github.com/vapor/fluent/blob/main/Sources/Fluent/Fluent+Cache.swift"
    click History "https://github.com/vapor/fluent/blob/main/Sources/Fluent/Fluent+History.swift"
    click Paginate "https://github.com/vapor/fluent/blob/main/Sources/Fluent/Fluent+Paginate.swift"
    click Sessions "https://github.com/vapor/fluent/blob/main/Sources/Fluent/Fluent+Sessions.swift"
    click CW "https://github.com/vapor/fluent/tree/main/Sources/Fluent/Concurrency/"
    click Exports "https://github.com/vapor/fluent/blob/main/Sources/Fluent/Exports.swift"
    click PageLimit "https://github.com/vapor/fluent/blob/main/Sources/Fluent/PageLimit.swift"
    click Docs "https://github.com/vapor/fluent/tree/main/Sources/Fluent/Docs.docc/"
    click Tests "https://github.com/vapor/fluent/tree/main/Tests/FluentTests/"

    %% Styles
    classDef host fill:#D0E8FF,stroke:#000,stroke-width:1px
    classDef integration fill:#DFFFE0,stroke:#4CAF50,stroke-width:1px
    classDef core fill:#FFE4B5,stroke:#FF8C00,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#888,stroke-width:1px
    classDef dev fill:#FFFFFF,stroke:#555,stroke-dasharray:5 5,stroke-width:1px
    classDef tests fill:#F3E5F5,stroke:#9C27B0,stroke-width:1px
```
