Setup repo: migrate architecture specs, code stubs, and tasks from alkhub_ts

Copy architecture docs, ADRs, storage domain specs, research, reviews, and 56 storage architecture tasks from the alkhub_ts monorepo. Adapt for standalone @alkdev/hub repo structure (src/ not packages/hub/). Sanitize all sensitive information: - Replace private IPs (10.0.0.1) with localhost defaults - Remove internal server hostnames (dev1, ns528096) - Replace /workspace/ private paths with npm package references - Remove hardcoded credentials from examples - Rewrite infrastructure.md without private network details Add Deno project scaffolding: deno.json (pinned deps), .gitignore, AGENTS.md, entry point. Migrate existing code stubs (crypto, config types, logger) with updated import paths.
2026-05-25 10:56:32 +00:00
parent 3e3f12d2d5
commit 2b63cda1c7
120 changed files with 11714 additions and 2 deletions
--- a/docs/architecture/infrastructure.md
+++ b/docs/architecture/infrastructure.md
@@ -0,0 +1,126 @@
+---
+status: draft
+last_updated: 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.
+
+```bash
+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.
+
+```bash
+# Local development with Docker Compose
+docker compose up postgres redis
+deno task dev
+```
+
+## Health Check
+
+```dockerfile
+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](hub-config.md) — Config system, encrypted fields, master key
+- [hub-startup.md](hub-startup.md) — Startup sequence, failure modes
+- [storage/README.md](storage/README.md) — Drizzle setup, migration strategy
+- [spoke-runner.md](spoke-runner.md) — Spoke authentication
+- [pubsub-redis.md](pubsub-redis.md) — Redis EventTarget configuration