Architecture › Platform Overview
Authority by Domain
| Service | Owns | Port | Tech |
|---|
| ada-core | runs/, bank.db, router-state.json, events.ndjson | none (IPC only) | Node.js 22 CLI, CommonJS |
| ada-api | conversations, workspaces, messages, sessions, run_links | :3001 (REST + WS) | Fastify 4, Drizzle ORM, SQLite WAL |
| ada-ui | UI state only (Zustand, TanStack cache) | :7777 | Next.js 15, React 19, Tailwind v4 |
IPC Event Flow
# ada-core emits events via Unix socket
ada-core (.claude/ada-core.sock)
→ IPC NDJSON + HMAC
→ ada-api receives, upserts DB, broadcasts WebSocket
→ ada-ui receives via WS, updates Zustand store
# Fallback chain (3 layers)
Layer 1: Unix socket push (always local mode)
Layer 2: TCP 127.0.0.1:3099 (server mode / socket absent)
Layer 3: FSWatch events.ndjson replay (IPC unavailable)
Startup Order
ada server start
# 1. ada-core daemon → wait .claude/ada-core.sock (timeout 10s)
# 2. ada-api → wait GET /api/health 200 (timeout 15s)
# 3. ada-ui → wait GET :7777 200 (timeout 20s)
ada server status
# → ada-core ✅ (socket .claude/ada-core.sock)
# → ada-api ✅ (:3001, SQLite ada-api.db OK)
# → ada-ui ✅ (:7777, connected to ada-api)
Fault Isolation
| Service Down | Impact | Behavior |
|---|
ada-ui | UI inaccessible | ada-core & ada-api continue; runs not lost |
ada-api | UI disconnected; no new commands | ada-core continues current runs; NDJSON buffers events |
ada-core | No new runs | ada-api & ada-ui remain up; history browsable |