hub/docs/architecture/infrastructure.md

status, last_updated

status	last_updated
draft	2026-05-25

Infrastructure: Server & Network Layout

Overview

The hub runs as a Docker container on a dedicated server, connecting to Postgres and Redis. Spokes connect to the hub over the internet via WebSocket.

Note

: This document describes the runtime architecture and configuration patterns. Specific server IPs, hostnames, and credentials are managed through the encrypted config system (see hub-config.md) and are NOT stored in this repository.

Server Requirements

Hub Server

Property	Requirement
Runtime	Deno (latest stable)
HTTP	Hono server on configured port
WebSocket	Hono WebSocket upgrade at /ws
Postgres	16+ (connected via encrypted config)
Redis	7+ (connected via encrypted config)
TLS	Via reverse proxy (nginx, caddy)

Spoke Runtime

Any environment with Deno and a WebSocket connection to the hub. No Postgres, no Redis, no HTTP server needed.

Network Architecture

Internet
    │
    ├─── Hub (api.alk.dev or configured hostname)
    │    ├── Hono HTTP server
    │    ├── WebSocket endpoint (/ws)
    │    ├── MCP endpoint (/mcp)
    │    ├── Postgres connection (encrypted config)
    │    └── Redis connection (encrypted config)
    │
    └─── Spokes (dev env, compute, client)
         └── WebSocket connection to hub

Postgres

• Version: 16+
• Connection: Configured via HubConfig.postgres (encrypted in config file)
• Auth: Credentials in encrypted config, never in environment variables
• Database: alkdev (default, configurable)
• Migrations: Drizzle ORM programmatic migrator at startup (see hub-startup.md)
• Accessible from: Hub container only (or WireGuard VPN for development)

See storage/README.md for Drizzle setup and migration strategy.

Redis

• Version: 7+
• Connection: Configured via HubConfig.redis (encrypted in config file)
• Usage: PubSub event transport, API key cache, session token cache, spoke health
• Two connections: One for publishing, one for subscribing (Redis pub/sub requires dedicated subscriber)

See pubsub-redis.md for Redis EventTarget configuration.

Deployment

Hub (Docker)

The hub reads config from /etc/alkhub/config.json and master key from /run/secrets/hub_master_key. See hub-config.md for the full config system and hub-startup.md for the startup sequence.

docker run -d \
  --name alkdev-hub \
  -p <host>:<port>:3000 \
  --tmpfs /run/secrets:mode=0400,uid=0 \
  -v /path/to/config.json:/etc/alkhub/config.json:ro \
  -v /path/to/master-key:/run/secrets/hub_master_key:ro \
  alkdev/hub:latest

A reverse proxy (nginx, caddy) handles TLS termination and proxies to the hub.

Development

For local development, Postgres and Redis can be run via Docker Compose or connected to over a VPN. The hub's development: true flag enables pretty-print logging and stricter error handling.

# Local development with Docker Compose
docker compose up postgres redis
deno task dev

Health Check

HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1

The /health endpoint returns:

• 200 { "status": "ok" } when all systems ready
• 503 { "status": "starting", "step": "<current>" } during startup
• 503 { "status": "degraded", "issues": [...] } if a subsystem fails after startup

Step names: resolve-config, load-config, init-logger, connect-postgres, run-migrations, connect-redis, init-keyring, init-drizzle, init-subsystems, start-server, ready

Security

• No secrets in environment variables: All secrets come from encrypted config or Docker secrets (see hub-config.md)
• No secrets in git: The .gitignore excludes .env*, *.key, *.pem, dev config files
• Config file encryption: Sensitive fields are AES-256-GCM encrypted, see hub-config.md
• Postgres: Not exposed to public internet. Connection details in encrypted config only
• Redis: Not exposed to public internet. Connection details in encrypted config only
• API keys: Managed by keypal, stored in api_keys table (hashed, never plaintext)
• Client secrets: Encrypted at rest with key versioning (see ADR-008)
• WebSocket auth: Bearer token at upgrade or first message (see spoke-runner.md Open Questions)

References

• hub-config.md — Config system, encrypted fields, master key
• hub-startup.md — Startup sequence, failure modes
• storage/README.md — Drizzle setup, migration strategy
• spoke-runner.md — Spoke authentication
• pubsub-redis.md — Redis EventTarget configuration