# vapor/fluent-mysql-driver architecture

> Architecture diagram of the GitHub repository vapor/fluent-mysql-driver, 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-mysql-driver
- Repository: https://github.com/vapor/fluent-mysql-driver

## Overview

##### Project Type and Purpose
- This is an open-source Swift driver library (“FluentMySQLDriver”) that implements a MySQL backend for Vapor’s Fluent ORM.
- Its main responsibility is to adapt FluentKit’s generic ORM calls into MySQL-specific SQL statements, manage async connections via MySQLNIO, and pool them with AsyncKit.

##### Key Components (to represent as distinct nodes)
a. FluentKit (ORM Abstraction)
- Exposes Model/Query APIs to user applications
- Calls into a “DatabaseDriver” protocol
b. FluentMySQLDriver (Adapter Layer)
- FluentMySQLConfiguration.swift
- FluentMySQLDatabase.swift
- FluentMySQLDriver.swift
- MySQLConverterDelegate.swift (translates ORM types → MySQL types)
- MySQLError+Database.swift, FluentMySQLError.swift (error mapping)
- MySQLRow+Database.swift (row decoding)
c. SQLKit (Generic SQL Builder)
- Defines SQL AST and query serialization interfaces
d. MySQLKit (MySQL-specific SQLKit Driver)
- Serializes SQLKit AST to MySQL wire protocol
e. MySQLNIO (Async Client)
- Manages low-level TCP framing & protocol encoding/decoding
f. AsyncKit (Connection Pooling)
- Provides pooling around MySQLNIO connections
g. MySQL Server (External System)

##### Component Relationships and Data Flow
- User App → FluentKit APIs →
- FluentMySQLDriver implements FluentKit’s `DatabaseDriver` →
- FluentMySQLDriver uses SQLKit to build queries →
- SQLKit AST passed to MySQLKit →
- MySQLKit sends serialized queries via MySQLNIO →
- MySQLNIO opens/manages TCP connections →
- AsyncKit wraps MySQLNIO in a connection pool →
- Responses flow back up: MySQLNIO → MySQLKit → FluentMySQLDriver (error/row decoding) → FluentKit → User App

##### Architectural Patterns and Principles
- Adapter/Facade: FluentMySQLDriver sits between FluentKit and SQLKit/MySQLKit.
- Separation of Concerns:
- ORM Layer (FluentKit)
- SQL Building (SQLKit)
- Driver Implementation (FluentMySQLDriver)
- Async Networking (MySQLNIO + AsyncKit)
- Dependency Injection: configuration objects passed into the driver.
- Protocol-Oriented Design: FluentKit defines protocols, then the driver conforms.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Consumer
    UA["User Application"]:::external
    UA -->|"calls Model APIs"| FK["FluentKit"]:::external

    %% Adapter Layer with internals
    subgraph "FluentMySQLDriver" 
        direction TB
        FConfig["FluentMySQLConfiguration.swift"]:::driver
        FDatabase["FluentMySQLDatabase.swift"]:::driver
        FDriver["FluentMySQLDriver.swift"]:::driver
        Converter["MySQLConverterDelegate.swift"]:::driver
        ErrMap1["MySQLError+Database.swift"]:::driver
        ErrMap2["FluentMySQLError.swift"]:::driver
        RowMap["MySQLRow+Database.swift"]:::driver
        Exports["Exports.swift"]:::driver
    end
    FK -->|"DatabaseDriver protocol"| FDriver
    FDriver -->|"configures via"| FConfig

    %% SQL Building
    FDriver -->|"buildQuery()"| SK["SQLKit"]:::external
    SK -->|"AST"| MK["MySQLKit"]:::external

    %% Connection Pooling & Networking
    MK -->|"execute(sql)"| AK["AsyncKit\n(Connection Pool)"]:::external
    AK -->|"acquire connection"| NIO["MySQLNIO"]:::external
    NIO -->|"open TCP"| DB["MySQL Server"]:::db
    NIO -->|"fetchRows() / responses"| MK
    MK -->|"row decoding & errors"| Converter
    Converter -->|"map to ORM types"| FK

    %% Documentation
    Docs["API Docs (Docs.docc)"]:::docs
    UA -.-> Docs

    %% Tests
    Tests["Driver Tests"]:::test

    %% Click Events
    click FConfig "https://github.com/vapor/fluent-mysql-driver/blob/main/Sources/FluentMySQLDriver/FluentMySQLConfiguration.swift"
    click FDatabase "https://github.com/vapor/fluent-mysql-driver/blob/main/Sources/FluentMySQLDriver/FluentMySQLDatabase.swift"
    click FDriver "https://github.com/vapor/fluent-mysql-driver/blob/main/Sources/FluentMySQLDriver/FluentMySQLDriver.swift"
    click Converter "https://github.com/vapor/fluent-mysql-driver/blob/main/Sources/FluentMySQLDriver/MySQLConverterDelegate.swift"
    click ErrMap1 "https://github.com/vapor/fluent-mysql-driver/blob/main/Sources/FluentMySQLDriver/MySQLError+Database.swift"
    click ErrMap2 "https://github.com/vapor/fluent-mysql-driver/blob/main/Sources/FluentMySQLDriver/FluentMySQLError.swift"
    click RowMap "https://github.com/vapor/fluent-mysql-driver/blob/main/Sources/FluentMySQLDriver/MySQLRow+Database.swift"
    click Exports "https://github.com/vapor/fluent-mysql-driver/blob/main/Sources/FluentMySQLDriver/Exports.swift"
    click Docs "https://github.com/vapor/fluent-mysql-driver/blob/main/Sources/FluentMySQLDriver/Docs.docc"
    click Tests "https://github.com/vapor/fluent-mysql-driver/blob/main/Tests/FluentMySQLDriverTests/FluentMySQLDriverTests.swift"

    %% Styles
    classDef driver fill:#blue,stroke:#000,color:#fff;
    classDef external fill:#9f6,stroke:#060,color:#000;
    classDef db fill:#bbb,stroke:#666,color:#000,stroke-dasharray: 5 5;
    classDef docs fill:#ffeb3b,stroke:#b58900,color:#000;
    classDef test fill:#f0f0f0,stroke:#00f,color:#000;
```
