# vapor/core architecture

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

## Overview

##### Project type and purpose
- This is an open-source Swift package (“vapor/core”) that provides foundational utilities for server-side Swift development.
- It is not a standalone application but a modular library offering asynchronous primitives, byte‐level operations, core data types/reflection, OS abstractions, and debugging tools.

##### File structure
- Top-level artifacts:
- Package.swift – Swift Package Manager manifest
- Sources/ – module source code, subdivided into Async, Bits, COperatingSystem, Core, Debugging
- Tests/ – unit tests mirroring each module
- Each subdirectory under Sources is its own Swift module, e.g., Async, Bits, Core, etc.
- No deployment or network configuration; this is a pure-code library.

##### README
- Confirms the package is “core” for the Vapor ecosystem.

##### Main components & interactions
- Async: FutureType, QueueHandler, Worker, Async+NIO bridging
- Bits: ByteBuffer extensions, Byte manipulations, Data ↔ Bytes
- COperatingSystem: thin wrapper over libc
- Core: file/directory utilities, process execution, reflection, media types, Base64/Hex coders
- Debugging: error demangling, SourceLocation, Debuggable protocol
- Tests (optional, shown as separate clusters)
- Core → Bits (e.g., DataCoders use ByteBuffer)
- Core → COperatingSystem (Process+Execute)
- Async → Core (FutureType uses Core.FutureEncoder, etc.)
- Async → COperatingSystem? (QueueHandler may use threads)
- Debugging → Core (Reflectable, CoreError)
- Optional: Async+NIO → Async & SwiftNIO (external)
c. Patterns & principles:
- Modular layering: low-level OS wrappers → bit/byte ops → core data types → async abstractions → debugging
- Futures/promises for async control flow
- Reflection for Codable & error introspection
d. Key technologies:
- Swift Package Manager
- SwiftNIO (via Async+NIO)
- Swift Codable & Reflection
- POSIX/libc interop

##### Putting it all together
- At the center: Core (green rectangle)
- To the left: Debugging (yellow) arrowing into Core

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Dependencies
    SWIFTNIO(("SwiftNIO")):::external
    LIBC(("libc")):::external

    %% Public Modules
    ASYNC["Async"]:::public
    CORE["Core"]:::public

    %% Low-Level Modules
    BITS["Bits"]:::low
    COSYS["COperatingSystem"]:::low

    %% Tooling Module
    DBG["Debugging"]:::tooling

    %% Module Relationships
    SWIFTNIO -->|bridges via Async+NIO| ASYNC
    LIBC -->|interop| COSYS
    ASYNC -->|uses| CORE
    ASYNC -->|uses threading| COSYS
    CORE -->|byte ops| BITS
    CORE -->|OS wrappers| COSYS
    DBG -->|reflects| CORE

    %% Test Clusters
    subgraph "Tests" 
        style Tests fill:none,stroke:none
        subgraph "AsyncTests" 
            direction TB
            AT["AsyncTests"]:::tests
            AT -->|tests| ASYNC
        end
        subgraph "BitsTests" 
            direction TB
            BT1["ByteBufferPeekTests"]:::tests
            BT2["ByteBufferRequireTests"]:::tests
            BT1 -->|tests| BITS
            BT2 -->|tests| BITS
        end
        subgraph "CoreTests" 
            direction TB
            CT1["CoreTests"]:::tests
            CT2["ReflectableTests"]:::tests
            CT1 -->|tests| CORE
            CT2 -->|tests| CORE
        end
        subgraph "DebuggingTests" 
            direction TB
            DT1["FooErrorTests"]:::tests
            DT2["GeneralTests"]:::tests
            DT3["TraceableTests"]:::tests
            DT1 -->|tests| DBG
            DT2 -->|tests| DBG
            DT3 -->|tests| DBG
        end
    end

    %% Click Events
    click ASYNC "https://github.com/vapor/core/tree/main/Sources/Async"
    click CORE "https://github.com/vapor/core/tree/main/Sources/Core"
    click BITS "https://github.com/vapor/core/tree/main/Sources/Bits"
    click COSYS "https://github.com/vapor/core/tree/main/Sources/COperatingSystem"
    click DBG "https://github.com/vapor/core/tree/main/Sources/Debugging"
    click AT "https://github.com/vapor/core/blob/main/Tests/AsyncTests/AsyncTests.swift"
    click BT1 "https://github.com/vapor/core/blob/main/Tests/BitsTests/ByteBufferPeekTests.swift"
    click BT2 "https://github.com/vapor/core/blob/main/Tests/BitsTests/ByteBufferRequireTests.swift"
    click CT1 "https://github.com/vapor/core/blob/main/Tests/CoreTests/CoreTests.swift"
    click CT2 "https://github.com/vapor/core/blob/main/Tests/CoreTests/ReflectableTests.swift"
    click DT1 "https://github.com/vapor/core/blob/main/Tests/DebuggingTests/FooErrorTests.swift"
    click DT2 "https://github.com/vapor/core/blob/main/Tests/DebuggingTests/GeneralTests.swift"
    click DT3 "https://github.com/vapor/core/blob/main/Tests/DebuggingTests/TraceableTests.swift"

    %% Styles
    classDef public fill:#a2f5a2,stroke:#2f7f2f,color:#000
    classDef low fill:#a2d2f5,stroke:#2f4f7f,color:#000
    classDef tooling fill:#f5e2a2,stroke:#7f6f2f,color:#000
    classDef tests fill:#dddddd,stroke:#888888,stroke-dasharray: 5 5,color:#000
    classDef external fill:#ffffff,stroke:#000000,stroke-dasharray: 2 2,color:#000
```
