# alchemy-swift/alchemy architecture

> Architecture diagram of the GitHub repository alchemy-swift/alchemy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alchemy-swift/alchemy
- Repository: https://github.com/alchemy-swift/alchemy

## Overview

##### Main Components Structure

a) Core Application Layer
- Application & Lifecycle management
- Plugin system
- Environment configuration
- Service container

b) HTTP Layer
- Routing system
- Middleware pipeline
- Request/Response handling
- Content negotiation
- Client functionality

c) Database Layer
- Query builder
- Migration system
- Model layer (Rune ORM)
- Multiple database support (MySQL, Postgres, SQLite)
- Connection pooling

d) Service Layers (show as parallel components)
- Cache (Memory, Redis, Database)
- Queue (Memory, Redis, Database)
- Events
- Filesystem
- Scheduler
- Redis
- Authentication
- Encryption
- Logging

##### Relationships and Data Flow

- HTTP requests flowing through the middleware pipeline to routes
- Database queries flowing through the query builder to database providers
- Service container connections to all components
- Event dispatch paths through the event bus
- Queue job processing flow
- Cache read/write paths

##### Implementation Details to Highlight

Architectural patterns:
- Provider pattern for services
- Middleware chain
- Database connection pooling
- Event dispatch system
- Job queue processing

**┌─ Application Core ─────────────────────┐**

- Plugin System    Lifecycle    Config  │

- HTTP Layer ──────────────────────────┤

- Router  Middleware  Request/Response  │

- Database Layer ────────────────────────┤

- Query Builder   Migrations   Models    │

- MySQL    Postgres    SQLite           │

- Services ───────────────────────────────┤

- Cache    Queue    Events    Filesystem  │

- Redis    Auth     Encrypt   Logging     │

- ┘

##### Additional Notes

- Version information (Swift 5.8+)
- Extension points for custom providers
- Async/await support
- Testing boundaries
- Macro expansion points

This architecture reflects Alchemy's "batteries included" philosophy while showing its modular, extensible nature.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Core["Application Core"]
        App[Application]
        Life[Lifecycle]
        Plugin[Plugin System]
        Env[Environment]
        Container[Service Container]
    end

    subgraph HTTP["HTTP Layer"]
        Router[Router]
        Mid[Middleware]
        ReqRes[Request/Response]
        Client[HTTP Client]
    end

    subgraph DB["Database Layer"]
        QB[Query Builder]
        Mig[Migration System]
        Model[Model Layer]
        
        subgraph DBProviders["Database Providers"]
            MySQL[MySQL]
            PG[Postgres]
            SQLite[SQLite]
        end
    end

    subgraph Services["Service Layer"]
        Cache[Cache]
        Queue[Queue]
        Events[Events]
        FS[Filesystem]
        Sched[Scheduler]
        Redis[Redis]
        Auth[Authentication]
        Encrypt[Encryption]
        Log[Logging]
    end

    subgraph Tools["Development Tools"]
        Testing[Testing Utilities]
        Macros[Macro System]
    end

    %% Core relationships
    App --> Life
    App --> Plugin
    App --> Env
    App --> Container

    %% HTTP relationships
    Router --> Mid
    Mid --> ReqRes
    Client --> ReqRes

    %% Database relationships
    QB --> DBProviders
    Mig --> DBProviders
    Model --> QB

    %% Service container connections
    Container --> Services
    Container --> HTTP
    Container --> DB

    %% Testing and Macro connections
    Testing --> App
    Macros --> App

    %% Styling
    classDef core fill:#a8d1f0
    classDef http fill:#90EE90
    classDef db fill:#FFB347
    classDef service fill:#DDA0DD
    classDef tools fill:#FFB6C1

    class App,Life,Plugin,Env,Container core
    class Router,Mid,ReqRes,Client http
    class QB,Mig,Model,MySQL,PG,SQLite db
    class Cache,Queue,Events,FS,Sched,Redis,Auth,Encrypt,Log service
    class Testing,Macros tools

    %% Click events
    click App "https://github.com/alchemy-swift/alchemy/blob/main/Alchemy/Sources/Application/Application.swift"
    click Life "https://github.com/alchemy-swift/alchemy/blob/main/Alchemy/Sources/Application/Lifecycle.swift"
    click Plugin "https://github.com/alchemy-swift/alchemy/blob/main/Alchemy/Sources/Application/Plugin.swift"
    click Env "https://github.com/alchemy-swift/alchemy/blob/main/Alchemy/Sources/Environment/Environment.swift"
    click Router "https://github.com/alchemy-swift/alchemy/blob/main/Alchemy/Sources/Routing/Router.swift"
    click Mid "https://github.com/alchemy-swift/alchemy/tree/main/Alchemy/Sources/HTTP/Middleware"
    click ReqRes "https://github.com/alchemy-swift/alchemy/blob/main/Alchemy/Sources/HTTP/Request.swift"
    click QB "https://github.com/alchemy-swift/alchemy/tree/main/Alchemy/Sources/Database/Query"
    click Mig "https://github.com/alchemy-swift/alchemy/tree/main/Alchemy/Sources/Database/Migrations"
    click Model "https://github.com/alchemy-swift/alchemy/tree/main/Alchemy/Sources/Database/Rune"
    click MySQL "https://github.com/alchemy-swift/alchemy/tree/main/Alchemy/Sources/Database/Providers/MySQL"
    click PG "https://github.com/alchemy-swift/alchemy/tree/main/Alchemy/Sources/Database/Providers/Postgres"
    click SQLite "https://github.com/alchemy-swift/alchemy/tree/main/Alchemy/Sources/Database/Providers/SQLite"
    click Cache "https://github.com/alchemy-swift/alchemy/tree/main/Alchemy/Sources/Cache"
    click Queue "https://github.com/alchemy-swift/alchemy/tree/main/Alchemy/Sources/Queue"
    click Events "https://github.com/alchemy-swift/alchemy/tree/main/Alchemy/Sources/Events"
    click FS "https://github.com/alchemy-swift/alchemy/tree/main/Alchemy/Sources/Filesystem"
    click Sched "https://github.com/alchemy-swift/alchemy/tree/main/Alchemy/Sources/Scheduler"
    click Redis "https://github.com/alchemy-swift/alchemy/tree/main/Alchemy/Sources/Redis"
    click Auth "https://github.com/alchemy-swift/alchemy/tree/main/Alchemy/Sources/Auth"
    click Encrypt "https://github.com/alchemy-swift/alchemy/tree/main/Alchemy/Sources/Encryption"
    click Log "https://github.com/alchemy-swift/alchemy/tree/main/Alchemy/Sources/Logging"
    click Testing "https://github.com/alchemy-swift/alchemy/tree/main/AlchemyTesting/Sources"
    click Macros "https://github.com/alchemy-swift/alchemy/tree/main/AlchemyPlugin/Sources"
```
