hub/docs/architecture/packages.md

status, last_updated

status	last_updated
draft	2026-05-25

Package Boundaries

Overview

This repository is @alkdev/hub — the hub API server. Spokes are separate packages/repos that connect to the hub via WebSocket. Published @alkdev/* packages are platform-agnostic npm dependencies.

@alkdev/hub → @alkdev/operations, @alkdev/pubsub, @alkdev/taskgraph, @alkdev/flowgraph

(spoke) → @alkdev/operations, @alkdev/pubsub

hub ←/→ (spoke)  (communicate via call protocol over WebSocket)

This Package: @alkdev/hub

The API server. Uses @alkdev/operations, @alkdev/pubsub, @alkdev/taskgraph, and @alkdev/flowgraph for operations, pubsub, call protocol, and task/workflow graph management. Adds HTTP serving, persistence, and coordination.

Modules (to be implemented):

• HTTP server (Hono) — serves API endpoints, MCP endpoint, WebSocket upgrade
• Storage (Drizzle+Postgres) — all persistent tables, migrations, relations
• Auth (keypal) — API key management, bearer token validation
• OpenAI proxy — LLM provider proxy, key management, rate limiting
• Coordination — coord.spawn/status/message/notify/abort/detect operations
• Agent sessions (AI SDK) — session management, message persistence, tool routing
• Call graph — runtime call graph tracking, observability
• Spoke management — RunnerPool, registration, dispatch, heartbeat
• Config — encrypted config loading, key ring management
• Crypto — AES-256-GCM encryption, PBKDF2 key derivation

Dependencies: @alkdev/operations, @alkdev/pubsub, @alkdev/taskgraph, @alkdev/flowgraph, @alkdev/typebox, @alkdev/drizzlebox, Hono, Drizzle+pg, ioredis, AI SDK, keypal, @hono/mcp

Does NOT depend on: Any spoke package — spokes are standalone repos that connect to the hub.

External @alkdev Packages

@alkdev/operations (npm, v0.1.0)

Shared operations and call protocol. Platform-agnostic. Used by both hub and spokes.

Exports:

• . — Core: types (OperationType, Identity, OperationContext, AccessControl, ErrorDefinition, IOperationDefinition, OperationSpec), registry, call protocol (PendingRequestMap, buildCallHandler, CallEventSchema, subscribe), access control (checkAccess, enforceAccess), error (CallError, InfrastructureErrorCode, mapError), env (buildEnv), scanner (scanOperations), validation (assertIsSchema, validateOrThrow, collectErrors), from_schema (FromSchema), response-envelope (ResponseEnvelope, localEnvelope, httpEnvelope, mcpEnvelope, unwrap, isResponseEnvelope)
• ./from-mcp — MCP tool adapter (optional peer: @modelcontextprotocol/sdk)
• ./from-typemap — Zod/Valibot schema adapters (optional peer: @alkdev/typemap)
• ./from-openapi — OpenAPI/SSE/HTTP service adapter

Dependencies: @alkdev/typebox, @alkdev/pubsub, @logtape/logtape

@alkdev/pubsub (npm, v0.1.0)

PubSub, event targets, and operators. Platform-agnostic.

Exports:

• . — Core: createPubSub, types, operators, Repeater (inlined)
• ./event-target-redis — Redis adapter (optional peer: ioredis)
• ./event-target-websocket-client — Spoke-side WebSocket adapter
• ./event-target-websocket-server — Hub-side WebSocket adapter
• ./event-target-worker — Web Worker adapter (host + thread sides)

Dependencies: None (runtime). ioredis is optional peer for Redis event target.

@alkdev/taskgraph (npm, v0.0.2)

Task graph construction, analysis, and frontmatter parsing.

Exports:

• . — TaskGraph class (fromTasks, fromRecords, fromJSON), analysis functions, schema enums, frontmatter parsing

Dependencies: @alkdev/typebox, graphology, yaml

@alkdev/flowgraph (npm, v0.1.0)

Workflow graph: DAG construction, ujsx templates, reactive execution, call/operation graphs.

Exports:

• ./graph — FlowGraph class, node/edge attribute types
• ./analysis — typeCompat, buildTypeEdges, topologicalOrder, validateGraph
• ./schema — CallNodeAttrs, CallEdgeAttrs, OperationNodeAttrs, CallStatus, CallEventMapValue
• ./reactive — WorkflowReactiveRoot
• ./component — ujsx template components (Operation, Sequential, Parallel, Conditional, Map)

Dependencies: @alkdev/typebox, graphology, preact

Rules

1. Published packages are platform-agnostic — they don't know about HTTP, WebSocket, or Redis connections (only Redis types for the EventTarget). Connection management lives in this repo.
2. Published packages are persistence-agnostic — they don't import Drizzle or pg. Storage lives here.
3. This repo does not depend on any spoke package — spokes connect via the call protocol over WebSocket.
4. Spokes don't need Redis — Redis connections are hub-internal. Spokes communicate via WebSocket.
5. Spokes don't need Postgres — all persistent state lives in the hub.
6. No circular deps — dependency direction is always toward published packages.
7. Published @alkdev/ packages must not import from @alkdev/hub.*
8. Pin dependency versions — use exact versions in deno.json, update manually when needed.

Storage Location Decision

Storage (Drizzle tables, migrations, client setup) lives in this repo (src/storage/). Rationale:

• Storage requires runtime Postgres connections → hub concern
• Storage schemas are hub-specific (sessions, mappings, spokes, call graphs)
• Spokes are ephemeral and stateless — they don't persist anything
• The @alkdev/drizzlebox pattern and all table schemas are documented in docs/architecture/storage/, the actual implementation is in src/storage/