# oakserver/oak architecture

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

- Interactive diagram: https://gitdiagram.com/oakserver/oak
- Repository: https://github.com/oakserver/oak

## Overview

a. Request Flow:
- Client Request → Runtime Adapter → Application → Middleware Pipeline → Response

b. Middleware Pipeline Flow:
- Middleware 1 → Middleware 2 → ... → Route Handler → ... → Middleware 2 → Middleware 1

##### Key Subsystems (Use nested containers)

a. Context System:
- Request Object
- Response Object
- State Management
- Cookies Handler
- WebSocket Manager

b. Router System:
- Route Patterns
- Route Parameters
- HTTP Method Handlers
- Nested Routers

##### Integration Points (Use interface connectors)

a. External Systems:
- Static File Server
- Server-Sent Events
- TLS/HTTPS Support
- Proxy Support

##### Specific Implementation Details

a. Request Processing:
- Request → Body Parser → Middleware Stack → Router → Handler → Response Formatter

b. Context Flow:
- Application State → Context Creation → Middleware Context → Response Generation

##### Important Notes

- Middleware execution is bidirectional
- Support for multiple runtime environments
- Built-in security features (cookies signing)
- Static file serving capabilities
- Error handling architecture

##### Technical Details to Highlight

- HTTP/HTTPS support
- WebSocket capabilities
- Server-Sent Events
- Static content serving
- Cookie management
- Body parsing options

##### Architecture Patterns

How Oak implements:
- Middleware pattern
- Router pattern
- Event-based error handling
- Plugin system

Remember to emphasize:
- The middleware-centric nature of the framework
- Runtime environment flexibility
- Error handling mechanisms
- Request/Response lifecycle
- Integration capabilities

This will provide a clear understanding of Oak's architecture while maintaining readability and usefulness for technical discussions.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Legend
        A1[Core Component]:::core
        A2[/Runtime Adapter/]:::runtime
        A3[Middleware]:::middleware
        A4[(External System)]:::external
        A5{{Error Handler}}:::error
    end

    subgraph Core
        App[Application]:::core
        Router[Router]:::core
        Context[Context]:::core
        ReqHandler[Request Handler]:::core
        ResHandler[Response Handler]:::core
        Pipeline[Middleware Pipeline]:::core
    end

    subgraph "Runtime Adapters"
        DenoServer[/Deno HTTP Server/]:::runtime
        NodeServer[/Node.js HTTP Server/]:::runtime
        BunServer[/Bun Runtime Server/]:::runtime
        CFWorker[/Cloudflare Workers/]:::runtime
    end

    subgraph "Middleware Layer"
        BuiltIn[Built-in Middleware]:::middleware
        Custom[Custom Middleware]:::middleware
        ErrorMW{{Error Handling}}:::error
    end

    subgraph "External Systems"
        StaticServer[(Static File Server)]:::external
        SSE[(Server-Sent Events)]:::external
        TLS[(TLS/HTTPS)]:::external
        Proxy[(Proxy Support)]:::external
    end

    subgraph "Context System"
        ReqObj[Request Object]:::core
        ResObj[Response Object]:::core
        State[State Management]:::core
        Cookies[Cookies Handler]:::core
        WS[WebSocket Manager]:::core
    end

    Client -->|Request| DenoServer & NodeServer & BunServer & CFWorker
    DenoServer & NodeServer & BunServer & CFWorker -->|Process| App
    App --> Pipeline
    Pipeline --> BuiltIn & Custom
    BuiltIn & Custom --> Router
    Router --> Context
    Context --> ReqObj & ResObj & State & Cookies & WS
    Context --> ErrorMW
    ErrorMW --> ResHandler
    ResHandler --> Client

    %% Click Events
    click App "https://github.com/oakserver/oak/blob/main/application.ts"
    click Router "https://github.com/oakserver/oak/blob/main/router.ts"
    click Context "https://github.com/oakserver/oak/blob/main/context.ts"
    click ReqHandler "https://github.com/oakserver/oak/blob/main/request.ts"
    click ResHandler "https://github.com/oakserver/oak/blob/main/response.ts"
    click Pipeline "https://github.com/oakserver/oak/blob/main/middleware.ts"
    click BuiltIn "https://github.com/oakserver/oak/tree/main/middleware"
    click DenoServer "https://github.com/oakserver/oak/blob/main/http_server_native.ts"
    click NodeServer "https://github.com/oakserver/oak/blob/main/http_server_node.ts"
    click BunServer "https://github.com/oakserver/oak/blob/main/http_server_bun.ts"
    click StaticServer "https://github.com/oakserver/oak/blob/main/middleware/serve.ts"
    click State "https://github.com/oakserver/oak/blob/main/utils/clone_state.ts"

    classDef core fill:#3498db,stroke:#2980b9,color:white
    classDef runtime fill:#e67e22,stroke:#d35400,color:white
    classDef middleware fill:#2ecc71,stroke:#27ae60,color:white
    classDef external fill:#9b59b6,stroke:#8e44ad,color:white
    classDef error fill:#e74c3c,stroke:#c0392b,color:white
```
