sequenceDiagram
participant UI as Browser
participant TH as kobi-ai /api/chat/threads
participant DB as Supabase
participant BFF as kobi-ai /api/ai/chat
participant ENG as kobi-agent-service
UI->>TH: POST /api/chat/threads
TH->>DB: insert kobi_chat_threads
DB-->>TH: thread UUID
TH-->>UI: thread UUID
UI->>UI: silent route replace (no hard remount)
UI->>BFF: POST /api/ai/chat (threadId=thread UUID)
BFF->>BFF: auth + allowlist + scope normalization
BFF->>ENG: POST /api/v1/chat + contract headers
ENG-->>BFF: chat response
BFF-->>UI: normalized response
sequenceDiagram
participant UI as Browser
participant BFF as kobi-ai /api/ai/stream
participant DB as Supabase
participant ENG as kobi-agent-service
UI->>BFF: POST /api/ai/stream
BFF->>BFF: auth + rate-limit + request validation
BFF->>DB: resolve thread/doc scope and canvas summary
BFF->>ENG: POST /api/v1/chat/stream
ENG-->>BFF: SSE events (chunk, tool_call, hitl_interrupt, done)
BFF->>BFF: strip canvas_mutation_intents if present
BFF->>BFF: map hitl_interrupt payload for UI
BFF-->>UI: SSE relay
sequenceDiagram
participant UI as Browser
participant BFF as kobi-ai /api/ai/resume
participant ENG as kobi-agent-service
participant MCP as kobi-mcp-server
UI->>BFF: POST /api/ai/resume (threadId, approved, decisions[])
BFF->>BFF: validate user/thread/project scope
BFF->>ENG: POST /api/v1/chat/resume + contract headers
ENG->>ENG: Command(resume={approved, reason, decisions[]})
alt approved tools
ENG->>MCP: call tools with approved=true + scope IDs
MCP-->>ENG: tool results
else rejected tools
ENG->>ENG: inject rejection ToolMessage
end
ENG-->>BFF: continuation response/SSE
BFF-->>UI: continuation output
sequenceDiagram
participant UI as Browser
participant BFF as kobi-ai /api/canvas/*
participant DB as Supabase
UI->>BFF: GET /api/canvas/workspace or /context
BFF->>BFF: auth + query validation + scope checks
BFF->>DB: read scoped rows
DB-->>BFF: rows
BFF-->>UI: canonical payload
UI->>BFF: POST /api/canvas/mutations
BFF->>BFF: auth + body validation + idempotency checks
BFF->>DB: apply operations
DB-->>BFF: result
BFF-->>UI: success or deterministic error
sequenceDiagram
participant ENG as LangGraph tool_executor
participant MCP as MCP /mcp/tools/call
participant DB as Supabase
ENG->>ENG: ensure_thread_exists(thread_id)
ENG->>MCP: call tool with approved, userId, threadId, projectId, agentType
MCP->>MCP: authenticateRequest + validateToolAccess + mutation context
MCP->>DB: execute read/write if allowed
DB-->>MCP: persisted or idempotent replay
MCP-->>ENG: tool response or structured error
