System Overview

System Overview

System Shape

KOBI runtime is split into four cooperating domains:

• Browser UI in kobi-ai for chat/canvas interaction.
• Next.js BFF in kobi-ai for authenticated APIs and engine proxying.
• FastAPI engine in kobi-agent-service for LangGraph orchestration.
• MCP server in kobi-mcp-server for tool execution and resource access.

Topology

flowchart TB
  UI[Browser UI]
  BFF[Next.js BFF in kobi-ai]
  ENG[kobi-agent-service]
  MCP[kobi-mcp-server]
  DB[(Supabase)]

  UI -->|/api/ai/* and /api/canvas/*| BFF
  UI -->|chat thread/message CRUD| DB

  BFF -->|service-to-service chat calls| ENG
  BFF -->|canvas workspace/context/mutations| DB

  ENG -->|/mcp/tools/call| MCP
  MCP -->|tool reads and writes| DB

Thread and Session Lifecycle

• UI creates a real thread row first (via /api/chat/threads) and then sends threadId to /api/ai/*.
• sessionId is still accepted as a deprecated alias at the BFF boundary.
• Missing thread or threadId="new" is rejected at BFF (400), not auto-generated.
• Engine requires thread context for chat/resume and validates trusted claim/header alignment.
• MCP mutating tools enforce approved execution context and scoped IDs (userId/threadId/projectId).
• Legacy auto-reply path is not part of current runtime. Generation path is BFF proxy -> engine workflow.

Detailed lifecycle behavior (URL sync, empty thread handling, batch status states) is documented in Thread and State Lifecycle.

Canvas Context Strategy

• BFF resolves canvas context from internal canvas service and forwards summary metadata (metadata.canvas_context, metadata.canvas_profile) to engine.
• BFF exposes /api/internal/canvas/context for internal engine pull with strict token + trusted claims.
• Current engine code does not actively call this internal pull route yet.

Active API Surface

BFF (kobi-ai)

• POST /api/chat/threads
• POST /api/ai/chat
• POST /api/ai/stream
• POST /api/ai/resume
• GET /api/canvas/workspace
• GET /api/canvas/context
• POST /api/canvas/mutations
• GET /api/internal/canvas/context (internal engine use)

Engine (kobi-agent-service)

• POST /api/v1/chat
• POST /api/v1/chat/stream
• POST /api/v1/chat/resume
• POST /api/v1/chat/stream/resume
• GET /api/v1/agents
• GET /health

MCP (kobi-mcp-server)

• POST /mcp/tools/list
• POST /mcp/tools/call
• POST /mcp/tools/catalog
• POST /mcp/resources/list
• POST /mcp/resources/read
• POST /health

Primary Data Tables

• Chat: kobi_chat_threads, kobi_chat_messages
• Canvas: kobi_canvas_nodes, kobi_canvas_edges
• Documents: kobi_documents, kobi_knowledge_embeddings
• Maps: kobi_map_locations
• Idea domain: kobi_ideas

Current Invariants

• Browser never calls engine directly.
• BFF never forwards raw user bearer token to engine.
• Engine contract headers and body claims must stay aligned (X-User-Id, X-Project-Id, X-Thread-Id, X-Agent-Type).
• MCP mutating tools require approved execution context and scoped IDs.