Memory
## DocuClear Clearspace — Architecture Decision: Hybrid Model (July 2026) ### Final Architecture - **Chat layer**: Vercel AI SDK → Workers AI (HTTP/SSE streaming) - **Real-time layer**: Cloudflare DO (WebSocket) for voice, collaborative editing, live preview, notifications - **Data layer**: SurrealDB (via container) for messages, threads, knowledge graph, entity extraction, traces - **Frontend**: assistant-ui React primitives with `useChat()` + `useAISDKRuntime()` ### Why This Over Pure Cloudflare Agents 1. Full control over agent loop and tool execution 2. SurrealDB is the brain (not SQLite in DO) 3. Stateless Worker = easier to reason about, scale, debug 4. No pre-1.0 dependencies 5. Natural SurrealDB integration for tools 6. We choose persistence (SurrealDB for everything) ### Why Not Pure Vercel AI SDK (without DO) 1. Need WebSocket for voice conversations 2. Need WebSocket for collaborative editing 3. Need WebSocket for live document preview 4. Need server-initiated push for notifications 5. DO handles stateful, bidirectional, session-scoped features ### Worker Routes - `/api/chat` — Vercel AI SDK streaming (stateless) - `/realtime/*` — WebSocket via DO (voice, editing, preview) - `/api/db/*` — SurrealDB DEFINE API endpoints (iPhone shortcuts, external tools) ### Key Pattern DO can call back into Worker's tool pipeline: DO receives audio → transcribes → calls /api/chat tool pipeline → streams response back over WebSocket ### Status: Ready to design backend architecture
Tags: architecture, decision, hybrid-model, worker-design, project:docuclear_clearspace, duplicate-candidate, kind:episodic, status:deprecated — Source: claude — 2026-07-18 21:29:15 UTC