# http4k/http4k-by-example architecture

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

- Interactive diagram: https://gitdiagram.com/http4k/http4k-by-example
- Repository: https://github.com/http4k/http4k-by-example

## Overview

##### Project type and purpose
- This is a standalone full-stack HTTP server application written in Kotlin using the http4k framework.
- Its business purpose is to model a building security system: authenticating users via OAuth, letting them enter or exit a building, querying current inhabitants, and logging those events to remote services.
- It also serves a simple web UI (Handlebars templates and static assets) and exposes a contract-driven OpenAPI v3 API.

##### File structure for architectural clues
- src/main/kotlin/verysecuresystems – core application code:
– Main.kt and SecuritySystemServer.kt bootstrap the HTTP server and routing.
– SecuritySystem.kt and domain.kt contain the in-memory business logic (the “inside vs. outside” state machine).
– api/ – HTTP API endpoints (KnockKnock, WhoIsThere, ByeBye).
– web/ – web UI endpoints (CreateUser, DeleteUser, ListUsers, ShowIndex, ShowError).
– external/ – HTTP adapters for remote systems: EntryLogger and UserDirectory clients.
– oauth/ – simple OAuth server implementation, token persistence, TokenChecker.
– diagnostic/ – health, uptime, ping and audit endpoints.
- Resources under src/main/resources:
– static files (CSS, swagger UI, OpenAPI specs).
– Handlebars templates for web UI.
- tests – layered testing strategy (unit, CDC for external adapters, functional, non-functional/OpenAPI contract tests, environment fakes).

##### README for technology stack and non-functional requirements
- HTTP framework: http4k, composable routing, Jackson for JSON.
- OAuth security for both API and UI, simple in-process OAuth server.
- OpenAPI v3 documentation auto-generated, served under /public/openapi.
- Handlebars templating for HTML UI, static resource serving.
- Zipkin header propagation for distributed tracing.
- Consumer-driven contracts and approval tests ensure reliable external integrations.

##### Main components
a. HTTP4K Server (entry point)
– Routing Layer, dividing traffic into:
- API Routes (secured via TokenChecker)
- Web UI Routes (Handlebars templates, static assets)
- Diagnostic Routes
- OpenAPI Documentation (static swagger UI)
b. Domain Core
– SecuritySystem: in-memory state machine tracking inhabitants
c. External HTTP Adapters
– UserDirectory service (remote HTTP)
– EntryLogger service (remote HTTP)
d. OAuth Subsystem
– In-process OAuth Server (handles /authorize, /token)
– InMemoryOAuthPersistence for tokens and clients
– SecurityServerAuthProvider for protecting routes
e. Infrastructure & cross-cutting
– Configuration (typesafe config via gradle.properties / java-version)
– Logging (http4k logging filter)
– Zipkin header propagation (http4k tracing filter)

##### Relationships and data flows
- Client → HTTP4K Server
- HTTP4K Server → SecurityServerAuthProvider → TokenChecker → Domain Core
- Domain Core → (on enter/exit) → EntryLogger HTTP adapter → remote EntryLogger service
- Domain Core → (on validity check) → UserDirectory HTTP adapter → remote UserDirectory service
- UI Routes → Domain Core → Templates (Handlebars) → HTML Response
- API Routes → Domain Core → JSON Response via Jackson
- HTTP4K Server → OpenAPI routes → Static swagger UI assets

##### Architectural patterns and design principles
- Hexagonal (ports & adapters): domain logic is isolated, with API, web, OAuth, and external HTTP clients as adapters.
- Single in-memory application process—no separate microservices.
- TDD with consumer-driven contracts for external adapters.
- Separation of concerns: routing, security, business logic, persistence, and external communications are clearly modularized.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Client Side"
        direction TB
        Browser["Browser UI / API Client"]:::client
    end

    %% In-Process Server
    subgraph "HTTP4K Server (In-Process)" 
        direction TB
        LoggingFilter["Logging Filter"]:::infra
        TracingFilter["Zipkin Tracing Filter"]:::infra
        SecurityServerAuthProviderNode["SecurityServerAuthProvider"]:::auth
        TokenCheckerNode["TokenChecker Filter"]:::auth

        LoggingFilter --> TracingFilter --> SecurityServerAuthProviderNode --> TokenCheckerNode

        subgraph "Routing Layer"
            direction TB
            subgraph "API Routes" 
                direction TB
                KnockKnock["KnockKnock API Route"]:::api
                WhoIsThere["WhoIsThere API Route"]:::api
                ByeBye["ByeBye API Route"]:::api
            end
            subgraph "Web UI Routes"
                direction TB
                CreateUser["CreateUser Web Route"]:::web
                DeleteUser["DeleteUser Web Route"]:::web
                ListUsers["ListUsers Web Route"]:::web
                ShowIndex["ShowIndex Web Route"]:::web
                ShowError["ShowError Web Route"]:::web
            end
            subgraph "Diagnostic Routes"
                direction TB
                Ping["Ping Endpoint"]:::diag
                Uptime["Uptime Endpoint"]:::diag
                Auditor["Audit Endpoint"]:::diag
            end
            subgraph "OpenAPI Documentation"
                direction TB
                OpenAPIUI["Swagger UI & OpenAPI Specs"]:::static
            end
        end

        Browser -->|HTTPS Request| LoggingFilter
        TokenCheckerNode -->|Route Dispatch| KnockKnock
        TokenCheckerNode -->|Route Dispatch| WhoIsThere
        TokenCheckerNode -->|Route Dispatch| ByeBye
        TokenCheckerNode -->|Route Dispatch| CreateUser
        TokenCheckerNode -->|Route Dispatch| DeleteUser
        TokenCheckerNode -->|Route Dispatch| ListUsers
        TokenCheckerNode -->|Route Dispatch| ShowIndex
        TokenCheckerNode -->|Route Dispatch| ShowError
        Browser -->|GET /public/openapi| OpenAPIUI

    end

    %% Domain Core
    subgraph "Domain Core" 
        direction TB
        SecuritySystemNode["SecuritySystem State Machine"]:::domain
        Inhabitants["Inhabitants Model"]:::domain
        DomainModels["Domain Models"]:::domain
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        EntryLoggerAdapter["EntryLogger Adapter"]:::external
        UserDirectoryAdapter["UserDirectory Adapter"]:::external
    end

    %% OAuth Subsystem
    subgraph "OAuth Subsystem"
        direction TB
        InMemoryOAuthPersistence["InMemoryOAuthPersistence"]:::auth
        SecurityServerAuthProviderNode2["SecurityServerAuthProvider"]:::auth
        TokenCheckerNode2["TokenChecker Filter"]:::auth
    end

    %% Cross connections
    KnockKnock -->|"Bearer Token"| SecuritySystemNode
    WhoIsThere -->|"Bearer Token"| SecuritySystemNode
    ByeBye -->|"Bearer Token"| SecuritySystemNode
    CreateUser -->|Form Data| SecuritySystemNode
    DeleteUser -->|Form Data| SecuritySystemNode
    ListUsers -->|Query| SecuritySystemNode
    ShowIndex -->|Query| SecuritySystemNode
    ShowError -->|Error| SecuritySystemNode
    SecuritySystemNode -->|onEnter/Exit| EntryLoggerAdapter
    SecuritySystemNode -->|onCheck| UserDirectoryAdapter
    OpenAPIUI -->|Static Serve| OpenAPIUI

    %% Click Events
    click Main "https://github.com/http4k/http4k-by-example/blob/master/src/main/kotlin/verysecuresystems/Main.kt"
    click SecuritySystemServer "https://github.com/http4k/http4k-by-example/blob/master/src/main/kotlin/verysecuresystems/SecuritySystemServer.kt"
    click KnockKnock "https://github.com/http4k/http4k-by-example/blob/master/src/main/kotlin/verysecuresystems/api/KnockKnock.kt"
    click WhoIsThere "https://github.com/http4k/http4k-by-example/blob/master/src/main/kotlin/verysecuresystems/api/WhoIsThere.kt"
    click ByeBye "https://github.com/http4k/http4k-by-example/blob/master/src/main/kotlin/verysecuresystems/api/ByeBye.kt"
    click Api "https://github.com/http4k/http4k-by-example/blob/master/src/main/kotlin/verysecuresystems/api/Api.kt"
    click Web "https://github.com/http4k/http4k-by-example/blob/master/src/main/kotlin/verysecuresystems/web/Web.kt"
    click CreateUser "https://github.com/http4k/http4k-by-example/blob/master/src/main/kotlin/verysecuresystems/web/CreateUser.kt"
    click DeleteUser "https://github.com/http4k/http4k-by-example/blob/master/src/main/kotlin/verysecuresystems/web/DeleteUser.kt"
    click ListUsers "https://github.com/http4k/http4k-by-example/blob/master/src/main/kotlin/verysecuresystems/web/ListUsers.kt"
    click ShowIndex "https://github.com/http4k/http4k-by-example/blob/master/src/main/kotlin/verysecuresystems/web/ShowIndex.kt"
    click ShowError "https://github.com/http4k/http4k-by-example/blob/master/src/main/kotlin/verysecuresystems/web/ShowError.kt"
    click Diagnostic "https://github.com/http4k/http4k-by-example/blob/master/src/main/kotlin/verysecuresystems/diagnostic/Diagnostic.kt"
    click Ping "https://github.com/http4k/http4k-by-example/blob/master/src/main/kotlin/verysecuresystems/diagnostic/Ping.kt"
    click Uptime "https://github.com/http4k/http4k-by-example/blob/master/src/main/kotlin/verysecuresystems/diagnostic/Uptime.kt"
    click Auditor "https://github.com/http4k/http4k-by-example/blob/master/src/main/kotlin/verysecuresystems/diagnostic/Auditor.kt"
    click OpenAPIUI "https://github.com/http4k/http4k-by-example/tree/master/src/main/resources/public/openapi"
    click SecuritySystemNode "https://github.com/http4k/http4k-by-example/blob/master/src/main/kotlin/verysecuresystems/SecuritySystem.kt"
    click DomainModels "https://github.com/http4k/http4k-by-example/blob/master/src/main/kotlin/verysecuresystems/domain.kt"
    click Inhabitants "https://github.com/http4k/http4k-by-example/blob/master/src/main/kotlin/verysecuresystems/Inhabitants.kt"
    click EntryLoggerAdapter "https://github.com/http4k/http4k-by-example/blob/master/src/main/kotlin/verysecuresystems/external/EntryLogger.kt"
    click UserDirectoryAdapter "https://github.com/http4k/http4k-by-example/blob/master/src/main/kotlin/verysecuresystems/external/UserDirectory.kt"
    click InMemoryOAuthPersistence "https://github.com/http4k/http4k-by-example/blob/master/src/main/kotlin/verysecuresystems/oauth/InMemoryOAuthPersistence.kt"
    click SecurityServerAuthProviderNode2 "https://github.com/http4k/http4k-by-example/blob/master/src/main/kotlin/verysecuresystems/oauth/SecurityServerAuthProvider.kt"
    click TokenCheckerNode2 "https://github.com/http4k/http4k-by-example/blob/master/src/main/kotlin/verysecuresystems/oauth/TokenChecker.kt"
    click IndexTemplate "https://github.com/http4k/http4k-by-example/blob/master/src/main/resources/verysecuresystems/web/Index.hbs"
    click ListUsersView "https://github.com/http4k/http4k-by-example/blob/master/src/main/resources/verysecuresystems/web/ListUsersView.hbs"
    click ErrorTemplate "https://github.com/http4k/http4k-by-example/blob/master/src/main/resources/verysecuresystems/web/Error.hbs"
    click StyleCSS "https://github.com/http4k/http4k-by-example/blob/master/src/main/resources/public/style.css"
    click GradleProps "https://github.com/http4k/http4k-by-example/blob/master/gradle.properties"
    click JavaVersion "https://github.com/http4k/http4k-by-example/blob/master/.java-version"
    click BuildScript "https://github.com/http4k/http4k-by-example/blob/master/build.gradle.kts"
    click Settings "https://github.com/http4k/http4k-by-example/blob/master/settings.gradle"
    click Gradlew "https://github.com/http4k/http4k-by-example/tree/master/gradlew"
    click GradleWrapper "https://github.com/http4k/http4k-by-example/tree/master/gradle/wrapper"

    %% Styles
    classDef client fill:#ADEFD1,stroke:#045D56,color:#000
    classDef infra fill:#E0E0E0,stroke:#888,color:#000
    classDef auth fill:#DCC6E0,stroke:#8B008B,color:#000
    classDef api fill:#A4DEF9,stroke:#036280,color:#000
    classDef web fill:#FFE4B5,stroke:#CC8400,color:#000
    classDef diag fill:#FFCCCC,stroke:#CC0000,color:#000
    classDef static fill:#D3D3D3,stroke:#666,color:#000
    classDef domain fill:#FFF4B2,stroke:#B5A200,color:#000
    classDef external fill:#B2F7EF,stroke:#009688,color:#000
```
