---
status: draft
last_updated: 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.