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.
This commit is contained in:
118
docs/architecture/overview.md
Normal file
118
docs/architecture/overview.md
Normal file
@@ -0,0 +1,118 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user