# vapor/routing-kit architecture

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

## Overview

##### Project type and purpose
- This is a Swift Package library (“RoutingKit”), not a standalone app.
- Its sole purpose is to provide a high-performance HTTP request router (trie-based) that frameworks (e.g., Vapor) can plug into.

##### Main components of the system
- Public API layer
– AnyRouter: type-erased, user-facing protocol conformer.
– Router protocol: defines core routing interface (e.g., insert(path:handler:), route(method:path:)).
- Core engine
– TrieRouter: concrete, high-performance trie implementation of Router.
– PathComponent: enum representing static segments, parameters, wildcards.
– Parameters: struct holding dynamic values extracted during routing.
- Package and Documentation
– Package.swift: Swift Package manifest (defines module, targets).
– Docs.docc: documentation bundle for DocC (resources, index.md, theme settings).
- Support modules
– Tests/RoutingKitTests: unit tests validating routing behavior.
– Benchmarks: performance measurement targets (RouterPerformance).

##### Relationships and data flow
1. An HTTP server (or web framework) receives a request (method, full path).
2. It invokes the public API (AnyRouter or Router protocol) to find a matching handler:
HTTPServer → AnyRouter (type-erased) → Router protocol → TrieRouter.match(...)
3. TrieRouter walks its internal Trie of PathComponent nodes to find the correct handler.
4. During the walk, dynamic path parameters are collected into a Parameters instance.
5. The handler and extracted Parameters are returned back up the chain to the HTTP server/framework.

##### Architectural patterns and design principles
- Protocol-oriented design: Router protocol abstracts routing logic; implementations can vary.
- Type erasure: AnyRouter hides concrete implementation details from consumers.
- Trie (prefix tree) data structure: enables O(m) lookup (m = number of path segments).
- Modular separation: routing core separate from tests, benchmarks, and documentation.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External HTTP Server
    HTTPServerFramework["HTTP Server / Framework"]:::external

    %% Public API Layer
    subgraph "Public API"
        direction TB
        AnyRouter["AnyRouter"]:::publicapi
        RouterProto["Router protocol"]:::publicapi
    end

    %% Core Engine
    subgraph "Core Engine"
        direction TB
        TrieRouter["TrieRouter"]:::core
        PathComponent["PathComponent"]:::core
        Parameters["Parameters"]:::core
    end

    %% Supporting Modules
    subgraph "Supporting Modules" 
        direction TB
        Docs["Docs.docc"]:::support
        Tests["RouterTests"]:::support
        Benchmarks["RouterPerformance"]:::support
    end

    %% Package Manifest
    PackageManifest["Package.swift"]:::support

    %% Data Flow
    HTTPServerFramework -->|"HTTPRequest(method, path)"| AnyRouter
    AnyRouter -->|"route(method, path)"| RouterProto
    RouterProto -->|"match(...)"| TrieRouter
    TrieRouter -->|"extract params"| Parameters
    TrieRouter -->|"RouteMatch + Parameters"| HTTPServerFramework

    %% Support links
    Docs -.->|Documentation| AnyRouter
    Tests -.->|Unit Tests| AnyRouter
    Benchmarks -.->|Benchmarks| AnyRouter

    %% Build config
    PackageManifest -->|"SwiftPM build"| AnyRouter
    PackageManifest -->|"SwiftPM build"| TrieRouter

    %% Click events
    click AnyRouter "https://github.com/vapor/routing-kit/blob/main/Sources/RoutingKit/AnyRouter.swift"
    click RouterProto "https://github.com/vapor/routing-kit/blob/main/Sources/RoutingKit/Router.swift"
    click TrieRouter "https://github.com/vapor/routing-kit/blob/main/Sources/RoutingKit/TrieRouter.swift"
    click PathComponent "https://github.com/vapor/routing-kit/blob/main/Sources/RoutingKit/PathComponent.swift"
    click Parameters "https://github.com/vapor/routing-kit/blob/main/Sources/RoutingKit/Parameters.swift"
    click PackageManifest "https://github.com/vapor/routing-kit/blob/main/Package.swift"
    click Docs "https://github.com/vapor/routing-kit/blob/main/Sources/RoutingKit/Docs.docc"
    click Tests "https://github.com/vapor/routing-kit/blob/main/Tests/RoutingKitTests/RouterTests.swift"
    click Benchmarks "https://github.com/vapor/routing-kit/blob/main/Benchmarks/RouterPerformance/RouterPerformance.swift"
    click Benchmarks "https://github.com/vapor/routing-kit/blob/main/Benchmarks/Package.swift"

    %% Styles
    classDef publicapi fill:#D0E1FF,stroke:#333,stroke-width:1px
    classDef core fill:#D0FFD0,stroke:#333,stroke-width:1px
    classDef support fill:#E0E0E0,stroke:#333,stroke-dasharray: 5 5
    classDef external fill:#FFF0D0,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
```
