Repository and Codebase Map

Repository and Codebase Map

This page is a practical “where to edit what” map. It reflects the active runtime path only.

System Repositories

Repository	Runtime Role	Primary Entry Points
kobi-ai	Browser UI + Next.js BFF	app/api/ai/*, app/api/canvas/*, app/api/chat/threads/route.js
kobi-agent-service	FastAPI + LangGraph orchestration	main.py, api/routes/chat.py, core/workflows/*
kobi-mcp-server	MCP tools/resources execution server	src/http-server.ts, src/tools/index.ts, src/resources/index.ts
kobi-web	Docs site	src/content/docs/docs/developer/*

kobi-ai (UI + BFF)

API routes

• AI proxy boundary: app/api/ai/_proxy.js
• Authenticated AI endpoints:
  • app/api/ai/chat/route.js
  • app/api/ai/stream/route.js
  • app/api/ai/resume/route.js
• Chat thread creation: app/api/chat/threads/route.js
• Canvas APIs:
  • app/api/canvas/workspace/route.js
  • app/api/canvas/context/route.js
  • app/api/canvas/mutations/route.js
  • app/api/internal/canvas/context/route.js (internal engine pull endpoint)

Chat state + UI orchestration

• Thread lifecycle and URL synchronization: src/modules/chat/hooks/useChatLifecycle.js
• Chat send orchestration: src/context/hooks/useChatSender.js
• HITL batch and action execution:
  • src/modules/chat/hooks/useChatActions.js
  • src/modules/chat/utils/hitlBatchState.js
  • src/context/ActionContext.jsx
• Chat shell and silent URL updates: src/modules/chat/components/ChatPane.jsx
• Action card states (pending, staged, submitted, approved/rejected): src/modules/chat/components/ActionProposal.jsx

Canvas and strategy writes

• Shared canvas service (BFF v2 API client): src/core/services/canvasService.js
• Strategy manual CRUD service: src/modules/strategy/services/strategyService.js

kobi-agent-service (Engine)

API and contract boundary

• App startup and routers: main.py
• Chat and resume endpoints: api/routes/chat.py
• Request/response schemas: api/schemas.py
• Internal BFF->engine contract validation: api/internal_contract.py

Workflow runtime

• Workflow registry and prompt assembly: core/workflows/registry.py
• Shared graph template: core/workflows/shared/builder.py
• Strategy graph: core/workflows/strategy/builder.py
• Context builder node (project background, token limit, knowledge docs): core/workflows/shared/nodes/context_builder.py
• Strategy context gate node: core/workflows/strategy/nodes/context_gate.py
• Strategy canvas execution node: core/workflows/strategy/nodes/canvas_agent.py
• HITL node and policy:
  • core/hitl/middleware.py
  • core/hitl/policy.py
• SSE stream shaping: core/streaming/sse.py

Persistence helpers

• Checkpointer: core/checkpointer/postgres.py
• Chat memory table adapter: services/chat_memory.py
• Thread existence validation for engine-side persistence: services/chat_threads.py

kobi-mcp-server (Tools/Resources)

Server entry points

• HTTP mode (used by engine runtime): src/http-server.ts
• Stdio mode (MCP native clients): src/index.ts

Tool dispatch and guards

• Tool registry and middleware composition: src/tools/index.ts
• Auth middleware: src/middleware/auth.ts
• Scope/phase gating middleware: src/middleware/toolGating.ts
• Tool scope source of truth: src/config/gating.ts

Tool implementations

• Shared tools (search): src/tools/shared/index.ts
• Idea tools: src/tools/idea/index.ts
• Strategy tools: src/tools/strategy/index.ts
• Maps tools: src/tools/maps/index.ts

Resource implementations

• Resource registry and handlers: src/resources/index.ts

Change Map by Scenario

Scenario	Primary Files
Add a new browser->engine metadata field	kobi-ai/app/api/ai/_proxy.js, kobi-web/src/content/docs/docs/developer/architecture/api-event-contracts.mdx
Change HITL approve/reject semantics	kobi-agent-service/core/hitl/middleware.py, kobi-ai/src/context/ActionContext.jsx, kobi-ai/src/modules/chat/hooks/useChatActions.js
Change batch decision UX	kobi-ai/src/modules/chat/hooks/useChatActions.js, kobi-ai/src/modules/chat/components/ActionProposal.jsx, kobi-ai/src/modules/chat/utils/hitlBatchState.js
Change strategy manual add/remove behavior	kobi-ai/src/modules/strategy/services/strategyService.js, kobi-ai/src/core/services/canvasService.js, kobi-ai/app/api/canvas/_service.js
Add a new MCP tool	kobi-mcp-server/src/tools/<family>/index.ts, kobi-mcp-server/src/tools/index.ts, kobi-mcp-server/src/config/gating.ts, kobi-agent-service/core/workflows/*/config.yaml
Change engine stream payload shape	kobi-agent-service/core/streaming/sse.py, kobi-ai/src/core/services/unifiedChatService.js, kobi-ai/src/modules/chat/hooks/useChatActions.js

Current Baseline Notes

• Browser inference path is BFF-only (/api/ai/*). There is no direct browser->engine path.
• Thread ID must be materialized before calling /api/ai/*; BFF does not auto-create thread IDs.
• Legacy auto-reply path is not part of current runtime flow in kobi-ai. Chat generation is routed through BFF proxy + engine workflow.