# areroketahi/vaporkit architecture

> Architecture diagram of the GitHub repository areroketahi/vaporkit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/areroketahi/vaporkit
- Repository: https://github.com/areroketahi/vaporkit

## Overview

VaporKit is a compile-time macro layer over Vapor that generates route registration, request extraction, and validation code, with opt-in runtime support for router discovery and application startup. The main workflow is a developer-declared router becoming Vapor routes that handle requests; separate branches provide validation, WebSockets, static parameter diagnostics, and OpenAPI extraction. The README documents these capabilities, while sampled source most clearly establishes route generation, typed extraction, and auto-registration; links for unsampled subsystems are limited to documented behavior and tree paths.

Main entry points: [`Sources/VaporKitMacros/Router/RouterMacro.swift`](https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKitMacros/Router/RouterMacro.swift) (Router macro), [`Sources/VaporKit/Router/Runtime/AutoRegisterRouter.swift`](https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKit/Router/Runtime/AutoRegisterRouter.swift) (Auto registration), [`Sources/VaporKit/Router/Router.swift`](https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKit/Router/Router.swift) (Router API), [`Sources/VaporKitMacros/Router/RouterMacro+Codegen.swift`](https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKitMacros/Router/RouterMacro%2BCodegen.swift) (Route codegen)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_routing["Routing"]
  node_router_api["Router API<br/>[Router.swift]"]
  node_route_macro["Router macro<br/>[RouterMacro.swift]"]
  node_route_parse["Route parsing"]
  node_route_metadata["Route metadata"]
  node_handler_metadata["Handler metadata"]
  node_route_codegen["Route codegen"]
  node_vapor_routes["Vapor routes"]
  node_generated_handler["Generated handler"]
  node_websocket["WebSocket routes"]
  node_static_check["Static parameter checks"]
end

subgraph group_startup["Startup"]
  node_vapor["Vapor application"]
  node_auto_config["Auto-register config"]
  node_auto_register["Auto registration"]
  node_route_discovery["Route discovery"]
  node_application_entry["Application entry"]
end

subgraph group_documentation["OpenAPI"]
  node_openapi_macro["OpenAPI extraction macros"]
  node_schema_macro["Schema macro"]
  node_schema_types["OpenAPI schemas"]
  node_openapi_discovery["OpenAPI discovery"]
  node_document_builder["Document builder"]
  node_openapi_exporter["Document exporter"]
  node_openapi_document["OpenAPI document"]
end

subgraph group_validation["Validation"]
  node_validation_macro["Validation macro"]
  node_validation_api["Validation rules"]
end

node_developer(("Application developer"))
node_vapor_request(("HTTP request"))

node_developer -->|"declares routes"| node_router_api
node_router_api -->|"expands macros"| node_route_macro
node_route_macro -->|"normalizes paths"| node_route_parse
node_route_macro -->|"extracts routes"| node_route_metadata
node_route_macro -->|"extracts handlers"| node_handler_metadata
node_route_macro -->|"generates code"| node_route_codegen
node_route_codegen -->|"registers handlers"| node_vapor_routes
node_vapor_request -->|"dispatches request"| node_vapor_routes
node_vapor_routes -->|"invokes handler"| node_generated_handler
node_generated_handler -->|"decodes values"| node_vapor_request
node_developer -->|"adopts entry point"| node_application_entry
node_application_entry -->|"loads configuration"| node_auto_config
node_auto_config -->|"calls registration"| node_auto_register
node_auto_register -->|"discovers routers"| node_route_discovery
node_auto_register -->|"registers collections"| node_vapor
node_developer -->|"annotates routes"| node_openapi_macro
node_openapi_macro -->|"references schemas"| node_schema_macro
node_schema_macro -->|"generates schema"| node_schema_types
node_openapi_discovery -->|"provides route metadata"| node_document_builder
node_document_builder -->|"builds document"| node_openapi_document
node_openapi_exporter -->|"exports document"| node_openapi_document
node_developer -->|"declares constraints"| node_validation_macro
node_validation_macro -->|"generates validation"| node_validation_api
node_developer -->|"declares WebSockets"| node_websocket
node_developer -->|"checks parameters"| node_static_check

click node_router_api "https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKit/Router/Router.swift"
click node_route_macro "https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKitMacros/Router/RouterMacro.swift"
click node_route_parse "https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKitMacros/Router/RouterMacro%2BRouteParsing.swift"
click node_route_metadata "https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKitMacros/Router/Metadata%20Extraction/RouterMacro%2BExtraction-Routes.swift"
click node_handler_metadata "https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKitMacros/Router/Metadata%20Extraction/RouterMacro%2BExtraction-Handlers.swift"
click node_route_codegen "https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKitMacros/Router/RouterMacro%2BCodegen.swift"
click node_auto_config "https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKit/Boot/Standard%20Configurations/AutoRegisterRoutesConfiguration.swift"
click node_auto_register "https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKit/Router/Runtime/AutoRegisterRouter.swift"
click node_route_discovery "https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKit/Router/Runtime/RouteDiscovery.swift"
click node_application_entry "https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKit/Boot/VaporApplication.swift"
click node_openapi_macro "https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKitMacros/Router/OpenAPI/RouterMacro%2BOpenAPIHandlers.swift"
click node_schema_macro "https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKitMacros/OpenAPISchemaMacro.swift"
click node_schema_types "https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKitOpenAPI/OpenAPISchema.swift"
click node_openapi_discovery "https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKit/Router/OpenAPI/OpenAPIDiscovery.swift"
click node_document_builder "https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKit/Router/OpenAPI/OpenAPIDocumentBuilder.swift"
click node_openapi_exporter "https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKit/Router/OpenAPI/OpenAPIExporter.swift"
click node_openapi_document "https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKit/Router/OpenAPI/OpenAPIDocument.swift"
click node_validation_macro "https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKitMacros/Validatable/ValidatableMacro.swift"
click node_validation_api "https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKit/Validation/ValidationRule.swift"
click node_websocket "https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKit/Router/Router%2BWebSocket.swift"
click node_static_check "https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKit/Router/Router%2BStaticCheck.swift"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_router_api,node_route_macro,node_route_parse,node_route_metadata,node_handler_metadata,node_route_codegen,node_vapor_routes,node_generated_handler,node_websocket,node_static_check toneBlue
class node_vapor,node_auto_config,node_auto_register,node_route_discovery,node_application_entry toneAmber
class node_openapi_macro,node_schema_macro,node_schema_types,node_openapi_discovery,node_document_builder,node_openapi_exporter,node_openapi_document,node_vapor_request toneMint
class node_validation_macro,node_validation_api toneRose
class node_developer toneIndigo
```

## Components

### Routing

- [Router API](https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKit/Router/Router.swift): `Sources/VaporKit/Router/Router.swift`
- [Router macro](https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKitMacros/Router/RouterMacro.swift): `Sources/VaporKitMacros/Router/RouterMacro.swift`
- [Route parsing](https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKitMacros/Router/RouterMacro%2BRouteParsing.swift): `Sources/VaporKitMacros/Router/RouterMacro+RouteParsing.swift`
- [Route metadata](https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKitMacros/Router/Metadata%20Extraction/RouterMacro%2BExtraction-Routes.swift): `Sources/VaporKitMacros/Router/Metadata Extraction/RouterMacro+Extraction-Routes.swift`
- [Handler metadata](https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKitMacros/Router/Metadata%20Extraction/RouterMacro%2BExtraction-Handlers.swift): `Sources/VaporKitMacros/Router/Metadata Extraction/RouterMacro+Extraction-Handlers.swift`
- [Route codegen](https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKitMacros/Router/RouterMacro%2BCodegen.swift): `Sources/VaporKitMacros/Router/RouterMacro+Codegen.swift`
- **Vapor routes**
- **Generated handler**
- [WebSocket routes](https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKit/Router/Router%2BWebSocket.swift): `Sources/VaporKit/Router/Router+WebSocket.swift`
- [Static parameter checks](https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKit/Router/Router%2BStaticCheck.swift): `Sources/VaporKit/Router/Router+StaticCheck.swift`

### Startup

- **Vapor application**
- [Auto-register config](https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKit/Boot/Standard%20Configurations/AutoRegisterRoutesConfiguration.swift): `Sources/VaporKit/Boot/Standard Configurations/AutoRegisterRoutesConfiguration.swift`
- [Auto registration](https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKit/Router/Runtime/AutoRegisterRouter.swift): `Sources/VaporKit/Router/Runtime/AutoRegisterRouter.swift`
- [Route discovery](https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKit/Router/Runtime/RouteDiscovery.swift): `Sources/VaporKit/Router/Runtime/RouteDiscovery.swift`
- [Application entry](https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKit/Boot/VaporApplication.swift): `Sources/VaporKit/Boot/VaporApplication.swift`

### OpenAPI

- [OpenAPI extraction macros](https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKitMacros/Router/OpenAPI/RouterMacro%2BOpenAPIHandlers.swift): `Sources/VaporKitMacros/Router/OpenAPI/RouterMacro+OpenAPIHandlers.swift`
- [Schema macro](https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKitMacros/OpenAPISchemaMacro.swift): `Sources/VaporKitMacros/OpenAPISchemaMacro.swift`
- [OpenAPI schemas](https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKitOpenAPI/OpenAPISchema.swift): `Sources/VaporKitOpenAPI/OpenAPISchema.swift`
- [OpenAPI discovery](https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKit/Router/OpenAPI/OpenAPIDiscovery.swift): `Sources/VaporKit/Router/OpenAPI/OpenAPIDiscovery.swift`
- [Document builder](https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKit/Router/OpenAPI/OpenAPIDocumentBuilder.swift): `Sources/VaporKit/Router/OpenAPI/OpenAPIDocumentBuilder.swift`
- [Document exporter](https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKit/Router/OpenAPI/OpenAPIExporter.swift): `Sources/VaporKit/Router/OpenAPI/OpenAPIExporter.swift`
- [OpenAPI document](https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKit/Router/OpenAPI/OpenAPIDocument.swift): `Sources/VaporKit/Router/OpenAPI/OpenAPIDocument.swift`

### Validation

- [Validation macro](https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKitMacros/Validatable/ValidatableMacro.swift): `Sources/VaporKitMacros/Validatable/ValidatableMacro.swift`
- [Validation rules](https://github.com/areroketahi/vaporkit/blob/main/Sources/VaporKit/Validation/ValidationRule.swift): `Sources/VaporKit/Validation/ValidationRule.swift`

### Other components

- **Application developer**
- **HTTP request**

## Connections

- Application developer → Router API: declares routes
- Router API → Router macro: expands macros
- Router macro → Route parsing: normalizes paths
- Router macro → Route metadata: extracts routes
- Router macro → Handler metadata: extracts handlers
- Router macro → Route codegen: generates code
- Route codegen → Vapor routes: registers handlers
- HTTP request → Vapor routes: dispatches request
- Vapor routes → Generated handler: invokes handler
- Generated handler → HTTP request: decodes values
- Application developer → Application entry: adopts entry point
- Application entry → Auto-register config: loads configuration
- Auto-register config → Auto registration: calls registration
- Auto registration → Route discovery: discovers routers
- Auto registration → Vapor application: registers collections
- Application developer → OpenAPI extraction macros: annotates routes
- OpenAPI extraction macros → Schema macro: references schemas
- Schema macro → OpenAPI schemas: generates schema
- OpenAPI discovery → Document builder: provides route metadata
- Document builder → OpenAPI document: builds document
- Document exporter → OpenAPI document: exports document
- Application developer → Validation macro: declares constraints
- Validation macro → Validation rules: generates validation
- Application developer → WebSocket routes: declares WebSockets
- Application developer → Static parameter checks: checks parameters