hub/docs/architecture/overview.md

status, last_updated

status	last_updated
draft	2026-05-25

@alkdev/hub Overview

Hub API server for the alk.dev platform.

What This Is

@alkdev/hub is the API server that coordinates work across spoke runners, manages agent sessions, and exposes operations via HTTP, WebSocket, and MCP. It's built on Deno + TypeScript. Spokes are separate packages (e.g., websearch-spoke) that connect via WebSocket, register their capabilities, and respond to operation calls from the hub.

This is the hub only — spokes are separate repos/packages. A spoke is just @alkdev/operations + @alkdev/pubsub WebSocket client connecting to this hub.

Repository Structure

@alkdev/hub/
  src/
    config/       — Configuration types (TypeBox schemas, encrypted config loading)
    crypto/       — Encryption utilities (AES-256-GCM, PBKDF2, key management)
    logger/       — Logtape configuration
    utils/        — Shared utilities
    storage/      — Drizzle table definitions, relations, migrations, queries
    server/       — Hono HTTP server, routes, middleware
    auth/         — API key auth (keypal), session tokens
    coordination/ — coord.spawn/status/message/notify/abort/detect operations
    redis/        — Redis EventTarget setup, event routing
    inference/    — OpenAI-compatible proxy, LLM key management
  docs/
    architecture/ — Architecture specifications (stable/draft)
    decisions/    — Architecture Decision Records (ADRs)
    research/     — Research documents
    reviews/      — Architecture and code reviews
  tasks/
    architecture/ — Architecture-phase tasks
  migrations/    — Drizzle SQL migrations

External Dependencies (npm)

Package	Version	Purpose
@alkdev/operations	0.1.0	Operations registry, call protocol, MCP adapter, ResponseEnvelope
@alkdev/pubsub	0.1.0	PubSub, event targets (Redis/WS/Worker), operators, EventEnvelope
@alkdev/taskgraph	0.0.2	Task graph construction, analysis, frontmatter
@alkdev/flowgraph	0.1.0	Workflow graph: DAG construction, ujsx templates, reactive execution
@alkdev/typebox	0.34.49	Runtime type schemas (fork of @sinclair/typebox 0.x LTS)
@alkdev/drizzlebox	0.1.0	TypeBox schema generation from Drizzle tables
hono	4.12.23	HTTP framework
drizzle-orm	0.45.2	Postgres ORM
ioredis	5.10.1	Redis client
keypal	0.2.0	API key management
pg	8.21.0	Postgres driver

Dependency direction: The hub depends on @alkdev/operations, @alkdev/pubsub, @alkdev/taskgraph, and @alkdev/flowgraph. Spokes depend on @alkdev/operations and @alkdev/pubsub. Hub and spokes never import from each other — they communicate via the call protocol over WebSocket.

What Exists

Module	Location	Status
Operations system	@alkdev/operations	Published v0.1.0
PubSub (createPubSub + operators)	@alkdev/pubsub	Published v0.1.0
TypedEventTarget	@alkdev/pubsub	Published v0.1.0
Redis EventTarget	@alkdev/pubsub	Published v0.1.0
WebSocket EventTarget (client+server)	@alkdev/pubsub	Published v0.1.0
Worker EventTarget	@alkdev/pubsub	Published v0.1.0
MCP client adapter	@alkdev/operations/from-mcp	Published v0.1.0
Call protocol (PendingRequestMap, CallHandler)	@alkdev/operations	Published v0.1.0
Access control (enforceAccess)	@alkdev/operations	Published v0.1.0
ResponseEnvelope	@alkdev/operations	Published v0.1.0
SchemaAdapter (Zod/Valibot)	@alkdev/operations/from-typemap	Published v0.1.0
SSE subscription handling	@alkdev/operations/from-openapi	Published v0.1.0
Task graph + analysis	@alkdev/taskgraph	Published v0.0.2
Flow graph (DAG, templates, reactive execution)	@alkdev/flowgraph	Published v0.1.0
Crypto utilities	src/crypto/	Stub (encrypt/decrypt/generateKey)
Config types	src/config/	Stub (TypeBox schemas)
Logger	src/logger/	Stub (basic logtape setup)

What Needs Implementation

Component	Spec	Priority
Storage (Drizzle+Postgres tables, migrations)	storage/	High
Hub HTTP server (Hono)	hub-architecture.md	High
Hub WebSocket server (spoke management)	spoke-runner.md	High
Config loading (loadConfig, resolveEncryptionKeys)	hub-config.md	High
OpenAI proxy (Hono)	agent-sessions.md	Medium
MCP server (@hono/mcp)	mcp-server.md	Medium
Agent sessions (AI SDK)	agent-sessions.md	Medium
Coordination operations	coordination.md	Medium
Call graph storage	call-graph.md, storage/	Medium
Spoke registration (RunnerPool)	spoke-runner.md	Medium
Operation graph	call-graph.md	Low
Call templates	call-graph.md	Low

Architecture Docs

All in docs/architecture/:

• overview.md — This document
• hub-architecture.md — Hub overview and component inventory
• call-graph.md — Call protocol, call graph, operation graph (uses @alkdev/flowgraph)
• spoke-runner.md — Spoke design, websocket transport, registration
• mcp-server.md — Discovery+call MCP interface (4 tools)
• operations.md — Operations system reference
• agent-sessions.md — AI SDK session model
• agent-roles.md — Agent roles and identity model
• coordination.md — From plugin to operations (coord.spawn etc.)
• pubsub-redis.md — Redis EventTarget adapter design
• hub-config.md — Configuration system (encrypted config, master key)
• hub-startup.md — Ordered startup sequence
• infrastructure.md — Server and network layout
• packages.md — Package boundaries and dependency rules
• storage/ — Drizzle+TypeBox+Postgres storage (README.md for patterns/setup, table-reference.md for schemas, per-domain schema files, tasks.md for task storage & taskgraph integration)

See AGENTS.md for project orientation, running instructions, and constraints.