kamidso-back/docs/kamidso/ARCHITECTURE.md

Kamidso Architecture v3 — Baseline

Status: Implementation baseline
Phase: Phase 1 — Agentic Data Foundation
Backend: Kamidso (product owner)
Product DB: MongoDB
Agent Runtime: DB-GPT (in-process engine)
Frontend: Existing Kamidso frontend + Agent Workspace capabilities

One-line definition

Kamidso owns Product, Data, Resources, and Orchestration; DB-GPT is an internal engine for Agent Planning, Tool Use, SQL/Python, Skills, AWEL, Knowledge, and Model Runtime.

Core invariants

1. Kamidso is the system of record.
2. DB-GPT is an execution engine, not the product authority.
3. Frontend talks only to Kamidso API (/api/kamidso/v1/*).
4. Engine IDs never become canonical product IDs.
5. All resources belong to a workspace.
6. Resources are authorized before engine invocation.
7. Large raw datasets are never blindly placed in LLM context.
8. Files are owned/stored by Kamidso.
9. Datasource credentials are never exposed to frontend or LLM.
10. SQL analysis is read-only by default.
11. Engine-specific events are normalized before reaching frontend.
12. Product contracts must not depend on DB-GPT internal schemas.
13. DB-GPT core modifications remain minimal.
14. Disabled future features must not leak into Phase 1 UX.
15. Agent planning remains DB-GPT's responsibility in Phase 1; Kamidso orchestrates engines/resources, not tool-level reasoning.

Runtime topology

Kamidso Backend Process (kamidso serve)
├── FastAPI — /api/kamidso/v1/*
├── Orchestrator + Resource Registry
├── MongoDB (product SoT)
├── Object Storage (files/artifacts)
└── DB-GPT Runtime (in-process, internal)

Kamidso DB ≠ DB-GPT DB. DB-GPT may use its own internal metadata store; it is not the product source of truth.

Dependency direction

Kamidso API → Application → Domain/Resources → Engine Interfaces → DB-GPT Adapter → DB-GPT

Reverse imports (dbgpt → kamidso) are forbidden except documented KAMIDSO_PATCH blocks.

Phase 1 scope

Build: bootstrap, Mongo repos, auth/workspace, conversations/runs/events, files/storage, resources, DB-GPT engine adapter, skills/models, SSE streaming, frontend contract migration, security limits, golden benchmarks.

Do not build: Ontology, Metrics, RCA, Reports, Dashboards, Widgets, Radar product UI, second agent loop in Kamidso.

Primary milestone

Login → Upload Excel via Kamidso Files → Ask structured question with ResourceRef → DB-GPT Python analysis → Kamidso events → answer → browser refresh recovery.

Repository layout — preserve vs product

This repository holds the API and the engine (kamidso/, configs/, skills/, tests/kamidso/, docs/kamidso/). The web UI is the frontend repository.

Removed from the repo: web/, examples/, packages/dbgpt-*, and the upstream Docusaurus site.

Keep

Path	Role
docs/kamidso/	Product architecture and runbooks
docker/	Mongo compose and the Walmart sample
configs/	Engine + product TOML
kamidso/	Product API and execution engine
frontend repository	Product UI
skills/	Product + engine skills
tests/kamidso/	Product tests

See REPO_LAYOUT.md for the production tree.