# hummingbird-project/hummingbird architecture

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

- Interactive diagram: https://gitdiagram.com/hummingbird-project/hummingbird
- Repository: https://github.com/hummingbird-project/hummingbird

## Overview

##### Project type and purpose
- This is a modular Swift server framework (Hummingbird). It is not a monolithic full-stack application but a library/framework built on top of SwiftNIO to provide HTTP server functionality, routing, middleware, TLS, HTTP/2, codable support, testing, and benchmarks.
- The README confirms it is a “lightweight, flexible modern web application framework” with built-in extensions (router, TLS, HTTP/2, testing) and a minimal core.

##### File structure
- Top-level directories:
- Sources: multiple modules: Hummingbird (high-level API), HummingbirdCore (NIO integration), HummingbirdHTTP2, HummingbirdTLS, HummingbirdRouter, HummingbirdTesting, PerformanceTest
- Tests: unit tests for each module
- Benchmarks: performance tests for routing
- docker, scripts: environment setup and CI scripts
- Patterns:
- Layered architecture: Application → Router → Middleware → Core HTTP server → NIO
- Extension modules plugged into the core (router, HTTP/2, TLS)
- Middleware pipeline pattern
- Adapter pattern for storage drivers

##### README for additional insights
- The user code instantiates a Router, configures routes, creates an Application with address configuration, and runs runService()
- It describes built-in and external extensions, highlighting the plug-in architecture

##### Detailed breakdown
- Layer 2: Network/TLS
- HummingbirdTLS.TLSChannel (encrypt/decrypt)
- Layer 3: Transport
- HummingbirdHTTP2.HTTP2Channel & HummingbirdCore.Server HTTP1Channel
- Layer 4: Core Server
- HummingbirdCore.ServerBuilder → RequestResponder
- Layer 5: Middleware
- LogRequestMiddleware → CORSMiddleware → FileMiddleware → MetricsMiddleware → TracingMiddleware
- Layer 6: Router
- Hummingbird.Router / HummingbirdRouter.RouterBuilder / TrieRouter
- Layer 7: Handlers
- User-defined GET /hello, etc.
- Layer 8: Codable
- JSONCoding & URLEncodedFormEncoder/Decoder
- Layer 9: Storage
- MemoryPersistDriver or custom PersistDriver
- Layer 10: Utils (ByteBuffer+foundation, DateCache, HexDigest)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layers Top to Bottom

    Client["Client (Browser/HTTP Client)"]:::client

    subgraph "Network/TLS Layer"
        TLS["HummingbirdTLS.TLSChannel"]:::extension
    end

    subgraph "Transport Layer"
        HTTP1["HTTP/1 Channel"]:::core
        HTTP2["HTTP/2 Channel"]:::extension
    end

    Core["HummingbirdCore.Server"]:::core

    Middleware["Middleware Pipeline"]:::core

    Router["Hummingbird.Router (TrieRouter)"]:::extension

    Handlers["User-defined Handlers"]:::app

    subgraph "Codable Support"
        CP["CodableProtocols"]:::extension
        JSONC["JSONCoding"]:::extension
        URLEncoded["URLEncodedFormEncoder/Decoder"]:::extension
    end

    Storage["Storage Adapters (PersistDriver)"]:::storage

    Utils["Utilities (Logging, Metrics, DateCache)"]:::util

    Testing["HummingbirdTesting"]:::extension

    %% Connections
    Client -->|"TCP/TLS"| TLS
    TLS -->|"decrypt/encrypt"| HTTP1
    TLS -->|"decrypt/encrypt"| HTTP2
    HTTP1 -->|"Request objects"| Core
    HTTP2 -->|"Request objects"| Core
    Core -->|"dispatch"| Middleware
    Middleware -->|"route"| Router
    Router -->|"invoke"| Handlers
    Handlers -->|"uses"| CP
    Handlers -->|"uses"| JSONC
    Handlers -->|"uses"| URLEncoded
    Handlers -->|"invoke"| Storage
    Handlers -->|"invoke"| Utils
    Core -->|"response"| HTTP1
    Core -->|"response"| HTTP2
    HTTP1 --> Client
    HTTP2 --> Client

    %% Click Events
    click TLS "https://github.com/hummingbird-project/hummingbird/tree/main/Sources/HummingbirdTLS"
    click HTTP1 "https://github.com/hummingbird-project/hummingbird/blob/main/Sources/HummingbirdCore/Server/HTTP/HTTP1Channel.swift"
    click HTTP2 "https://github.com/hummingbird-project/hummingbird/blob/main/Sources/HummingbirdHTTP2/HTTP2Channel.swift"
    click Core "https://github.com/hummingbird-project/hummingbird/blob/main/Sources/HummingbirdCore/Server/Server.swift"
    click Middleware "https://github.com/hummingbird-project/hummingbird/tree/main/Sources/Hummingbird/Middleware"
    click Router "https://github.com/hummingbird-project/hummingbird/tree/main/Sources/Hummingbird/Router"
    click CP "https://github.com/hummingbird-project/hummingbird/blob/main/Sources/Hummingbird/Codable/CodableProtocols.swift"
    click JSONC "https://github.com/hummingbird-project/hummingbird/blob/main/Sources/Hummingbird/Codable/JSON/JSONCoding.swift"
    click URLEncoded "https://github.com/hummingbird-project/hummingbird/tree/main/Sources/Hummingbird/Codable/URLEncodedForm"
    click Storage "https://github.com/hummingbird-project/hummingbird/tree/main/Sources/Hummingbird/Storage"
    click Utils "https://github.com/hummingbird-project/hummingbird/tree/main/Sources/Hummingbird/Utils"
    click Testing "https://github.com/hummingbird-project/hummingbird/tree/main/Sources/HummingbirdTesting"

    %% Styles
    classDef client fill:#dddddd,stroke:#333,stroke-width:1px
    classDef core fill:#A2D2FF,stroke:#0366D6,stroke-width:2px
    classDef extension fill:#C3F584,stroke:#398439,stroke-width:2px
    classDef storage fill:#FFE066,stroke:#D4A017,stroke-width:2px,shape:cylinder
    classDef util fill:#FFCBF2,stroke:#A0007A,stroke-width:2px
    classDef app fill:#FFC6A5,stroke:#D14D00,stroke-width:2px
```
