glm-5.1
2b63cda1c7
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.
118 lines
5.9 KiB
Markdown
118 lines
5.9 KiB
Markdown
---
|
|
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. |