How vapor/fluent works
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”