Data Models and Ownership

Data Models and Ownership

This page defines who is allowed to write each core table and how data is read across services.

Ownership Rule

• kobi-ai BFF owns browser-facing auth/scope validation and canvas mutation APIs.
• kobi-agent-service owns orchestration state and HITL resume semantics.
• kobi-mcp-server owns tool-level side effects and tool gating.
• Browser components in kobi-ai still perform direct user-scoped Supabase CRUD for chat thread/message rows.

Core Tables

Table	Primary Write Paths	Primary Read Paths	Main Owner
kobi_chat_threads	POST /api/chat/threads (kobi-ai)	kobi-ai chat services, BFF scope checks, MCP auth checks	kobi-ai
kobi_chat_messages	chatService.addMessage/updateMessage in browser (kobi-ai)	kobi-ai chat UI	kobi-ai
kobi_chat_memory	services/chat_memory.py (kobi-agent-service)	Engine context/history load	kobi-agent-service
kobi_canvas_nodes	POST /api/canvas/mutations (kobi-ai BFF), plus MCP strategy tool persistence	Canvas workspace/context APIs, strategy store load, engine context summary via BFF	Shared (kobi-ai + kobi-mcp-server)
kobi_canvas_edges	POST /api/canvas/mutations (kobi-ai BFF)	Canvas workspace/context APIs	kobi-ai
kobi_canvas_mutation_requests	Idempotency reserve/finalize in app/api/canvas/_service.js	BFF mutation replay/conflict checks	kobi-ai
kobi_documents	Upload/document flows in kobi-ai	BFF resolves attached_document_ids for engine metadata	kobi-ai
kobi_knowledge_embeddings	Knowledge indexing pipeline	Engine context_builder knowledge search	kobi-ai
kobi_ideas	MCP idea tools (create_chunk/create_idea/...)	Idea canvas/resource reads	kobi-mcp-server
kobi_map_locations	MCP maps tools (save_location)	Maps reads and UI render	kobi-mcp-server
kobi_project_teams	Project/team management flows	Team thread restoration in chat lifecycle	kobi-ai

Chat and Thread Data Split

Current runtime intentionally has two chat stores:

• Conversation UI rows: kobi_chat_messages (browser-facing, direct Supabase access in kobi-ai)
• Engine memory rows: kobi_chat_memory (engine-facing, written by kobi-agent-service)

The split is valid but means debugging must check both tables.

Canvas Mutation Guarantees

POST /api/canvas/mutations in kobi-ai provides:

• Scope checks (user_id, project_id, thread_id)
• Agent adapter validation (allowed_node_types, payload shape)
• Batched transactional behavior with rollback
• Idempotency persistence using kobi_canvas_mutation_requests

Common conflict classes:

• idempotency_payload_mismatch
• idempotency_in_progress
• node_already_exists
• node_not_found

These may surface as HTTP 409.

HITL and Mutation Context

Mutating MCP tools are guarded by:

• Auth context: userId/threadId/projectId in src/middleware/auth.ts
• Scope/phase gating: src/middleware/toolGating.ts
• Mutation context enforcement: approved=true + normalized actionId/idempotencyKey in src/tools/index.ts

This ensures tool side effects are linked to a resumed interrupt flow, not arbitrary calls.

Strategy Data Reality

Strategy items are stored as canvas nodes, not a dedicated strategy table.

• agent_id = "strategy"
• node_type = "strategy_item"
• data.framework, data.quadrant, data.content, data.priority

Manual strategy CRUD and agent-proposed strategy items both converge on kobi_canvas_nodes.

Non-Negotiable Invariants

• Every mutating path must include valid userId, threadId, and projectId.
• threadId must reference an existing kobi_chat_threads.id.
• Browser sends canonical threadId; engine-facing payload is normalized by BFF.
• No client should assume a fixed HITL batch size. Decision arrays are variable length.