How http4k/http4k-by-example works
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.