# 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

```text
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

```text
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/`](../../docker/) | Mongo compose and the Walmart sample |
| [`configs/`](../../configs/) | Engine + product TOML |
| [`kamidso/`](../../kamidso/) | Product API and execution engine |
| frontend repository | Product UI |
| [`skills/`](../../skills/) | Product + engine skills |
| [`tests/kamidso/`](../../tests/kamidso/) | Product tests |

See [REPO_LAYOUT.md](./REPO_LAYOUT.md) for the production tree.