# kakuibeyond/chatbi_mvp architecture

> Architecture diagram of the GitHub repository kakuibeyond/chatbi_mvp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kakuibeyond/chatbi_mvp
- Repository: https://github.com/kakuibeyond/chatbi_mvp

## Overview

ChatBI is a natural-language-to-SQL analytics application with both CLI and FastAPI/SSE entry points. Its main workflow validates a question, enriches a prompt with business rules and optional indicator/schema context, generates SQL, executes it under security controls, and formats results. A separate Plan-and-Execute agent decomposes complex analyses and can produce reports. The README documents additional retrieval and schema-generation capabilities; some internal connections are supported by the source index or README rather than complete excerpts, so unsampled implementation details are not inferred.

Main entry points: [`main.py`](https://github.com/kakuibeyond/chatbi_mvp/blob/master/main.py) (ChatBI system), [`schema_linker.py`](https://github.com/kakuibeyond/chatbi_mvp/blob/master/schema_linker.py) (Schema linker), [`llm_client.py`](https://github.com/kakuibeyond/chatbi_mvp/blob/master/llm_client.py) (LLM client), [`agent_planner.py`](https://github.com/kakuibeyond/chatbi_mvp/blob/master/agent_planner.py) (Plan executor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_cli["CLI<br/>[main.py]"]
  node_api["FastAPI service<br/>[api_service.py]"]
end

subgraph group_query["Query workflow"]
  node_chatbi["ChatBI system<br/>[main.py]"]
  node_parser["Query parser<br/>[query_parser.py]"]
  node_prompt["Prompt builder<br/>[prompt_builder.py]"]
  node_llm["LLM client<br/>[llm_client.py]"]
  node_formatter["Result formatter"]
end

subgraph group_knowledge["Business context"]
  node_indicators["Indicator knowledge"]
  node_indicator_rag["Indicator retrieval"]
  node_schema_linker["Schema linker<br/>[schema_linker.py]"]
  node_table_retriever["Table retrieval<br/>[table_retriever.py]"]
  node_field_matcher["Field matching<br/>[field_matcher.py]"]
  node_join_resolver["Join resolution<br/>[join_resolver.py]"]
end

subgraph group_agent["Agent analysis"]
  node_decomposer["Query decomposer"]
  node_planner["Plan executor<br/>[agent_planner.py]"]
  node_report["Report generator"]
end

subgraph group_runtime["Runtime and data"]
  node_runtime_factory["Runtime factory<br/>[runtime_factory.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_database["Database client<br/>[database.py]"]
  node_security["Query security<br/>[security.py]"]
  node_schema_generator["Schema generator"]
end

node_user(("Analyst"))
node_model_service{{"LLM API"}}
node_sql_database[("SQL database")]

node_user -->|"asks via CLI"| node_cli
node_user -->|"sends query"| node_api
node_cli -->|"runs query"| node_chatbi
node_api -->|"routes query"| node_chatbi
node_chatbi -->|"builds runtime"| node_runtime_factory
node_runtime_factory -->|"reads settings"| node_config
node_chatbi -->|"validates question"| node_parser
node_chatbi -->|"resolves indicators"| node_indicators
node_chatbi -->|"retrieves indicators"| node_indicator_rag
node_chatbi -->|"builds prompt"| node_prompt
node_prompt -->|"requests schema"| node_schema_linker
node_schema_linker -->|"retrieves tables"| node_table_retriever
node_schema_linker -->|"matches fields"| node_field_matcher
node_schema_linker -->|"resolves joins"| node_join_resolver
node_field_matcher -->|"uses retrieval"| node_table_retriever
node_chatbi -->|"generates SQL"| node_llm
node_llm -->|"calls API"| node_model_service
node_chatbi -->|"executes SQL"| node_database
node_database -->|"secures SQL"| node_security
node_database -->|"queries"| node_sql_database
node_chatbi -->|"formats results"| node_formatter
node_indicator_rag -->|"uses definitions"| node_indicators
node_planner -->|"decomposes question"| node_decomposer
node_planner -->|"executes steps"| node_chatbi
node_planner -->|"generates report"| node_report
node_report -->|"requests summary"| node_llm
node_decomposer -->|"generates plan"| node_llm
node_decomposer -->|"uses schema"| node_prompt
node_schema_generator -->|"reads schema"| node_sql_database

click node_cli "https://github.com/kakuibeyond/chatbi_mvp/blob/master/main.py"
click node_api "https://github.com/kakuibeyond/chatbi_mvp/blob/master/api_service.py"
click node_chatbi "https://github.com/kakuibeyond/chatbi_mvp/blob/master/main.py"
click node_parser "https://github.com/kakuibeyond/chatbi_mvp/blob/master/query_parser.py"
click node_prompt "https://github.com/kakuibeyond/chatbi_mvp/blob/master/prompt_builder.py"
click node_llm "https://github.com/kakuibeyond/chatbi_mvp/blob/master/llm_client.py"
click node_formatter "https://github.com/kakuibeyond/chatbi_mvp/blob/master/result_formatter.py"
click node_indicators "https://github.com/kakuibeyond/chatbi_mvp/blob/master/indicator_knowledge.py"
click node_indicator_rag "https://github.com/kakuibeyond/chatbi_mvp/blob/master/indicator_retriever.py"
click node_schema_linker "https://github.com/kakuibeyond/chatbi_mvp/blob/master/schema_linker.py"
click node_table_retriever "https://github.com/kakuibeyond/chatbi_mvp/blob/master/table_retriever.py"
click node_field_matcher "https://github.com/kakuibeyond/chatbi_mvp/blob/master/field_matcher.py"
click node_join_resolver "https://github.com/kakuibeyond/chatbi_mvp/blob/master/join_resolver.py"
click node_decomposer "https://github.com/kakuibeyond/chatbi_mvp/blob/master/query_decomposer.py"
click node_planner "https://github.com/kakuibeyond/chatbi_mvp/blob/master/agent_planner.py"
click node_report "https://github.com/kakuibeyond/chatbi_mvp/blob/master/report_generator.py"
click node_runtime_factory "https://github.com/kakuibeyond/chatbi_mvp/blob/master/runtime_factory.py"
click node_config "https://github.com/kakuibeyond/chatbi_mvp/blob/master/config.py"
click node_database "https://github.com/kakuibeyond/chatbi_mvp/blob/master/database.py"
click node_security "https://github.com/kakuibeyond/chatbi_mvp/blob/master/security.py"
click node_schema_generator "https://github.com/kakuibeyond/chatbi_mvp/blob/master/schema_generator.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_api toneBlue
class node_chatbi,node_parser,node_prompt,node_llm,node_formatter,node_sql_database toneAmber
class node_indicators,node_indicator_rag,node_schema_linker,node_table_retriever,node_field_matcher,node_join_resolver,node_model_service toneMint
class node_decomposer,node_planner,node_report toneRose
class node_runtime_factory,node_config,node_database,node_security,node_schema_generator,node_user toneIndigo
```

## Components

### Entry points

- [CLI](https://github.com/kakuibeyond/chatbi_mvp/blob/master/main.py): `main.py`
- [FastAPI service](https://github.com/kakuibeyond/chatbi_mvp/blob/master/api_service.py): `api_service.py`

### Query workflow

- [ChatBI system](https://github.com/kakuibeyond/chatbi_mvp/blob/master/main.py): `main.py`
- [Query parser](https://github.com/kakuibeyond/chatbi_mvp/blob/master/query_parser.py): `query_parser.py`
- [Prompt builder](https://github.com/kakuibeyond/chatbi_mvp/blob/master/prompt_builder.py): `prompt_builder.py`
- [LLM client](https://github.com/kakuibeyond/chatbi_mvp/blob/master/llm_client.py): `llm_client.py`
- [Result formatter](https://github.com/kakuibeyond/chatbi_mvp/blob/master/result_formatter.py): `result_formatter.py`

### Business context

- [Indicator knowledge](https://github.com/kakuibeyond/chatbi_mvp/blob/master/indicator_knowledge.py): `indicator_knowledge.py`
- [Indicator retrieval](https://github.com/kakuibeyond/chatbi_mvp/blob/master/indicator_retriever.py): `indicator_retriever.py`
- [Schema linker](https://github.com/kakuibeyond/chatbi_mvp/blob/master/schema_linker.py): `schema_linker.py`
- [Table retrieval](https://github.com/kakuibeyond/chatbi_mvp/blob/master/table_retriever.py): `table_retriever.py`
- [Field matching](https://github.com/kakuibeyond/chatbi_mvp/blob/master/field_matcher.py): `field_matcher.py`
- [Join resolution](https://github.com/kakuibeyond/chatbi_mvp/blob/master/join_resolver.py): `join_resolver.py`

### Agent analysis

- [Query decomposer](https://github.com/kakuibeyond/chatbi_mvp/blob/master/query_decomposer.py): `query_decomposer.py`
- [Plan executor](https://github.com/kakuibeyond/chatbi_mvp/blob/master/agent_planner.py): `agent_planner.py`
- [Report generator](https://github.com/kakuibeyond/chatbi_mvp/blob/master/report_generator.py): `report_generator.py`

### Runtime and data

- [Runtime factory](https://github.com/kakuibeyond/chatbi_mvp/blob/master/runtime_factory.py): `runtime_factory.py`
- [Configuration](https://github.com/kakuibeyond/chatbi_mvp/blob/master/config.py): `config.py`
- [Database client](https://github.com/kakuibeyond/chatbi_mvp/blob/master/database.py): `database.py`
- [Query security](https://github.com/kakuibeyond/chatbi_mvp/blob/master/security.py): `security.py`
- [Schema generator](https://github.com/kakuibeyond/chatbi_mvp/blob/master/schema_generator.py): `schema_generator.py`

### Other components

- **Analyst**
- **LLM API**
- **SQL database**

## Connections

- Analyst → CLI: asks via CLI (evidence: `README.md`)
- Analyst → FastAPI service: sends query (evidence: `README.md`)
- CLI → ChatBI system: runs query (evidence: `README.md`)
- FastAPI service → ChatBI system: routes query (evidence: `README.md`)
- ChatBI system → Runtime factory: builds runtime (evidence: `main.py`)
- Runtime factory → Configuration: reads settings (evidence: `runtime_factory.py`)
- ChatBI system → Query parser: validates question (evidence: `main.py`)
- ChatBI system → Indicator knowledge: resolves indicators (evidence: `main.py`)
- ChatBI system → Indicator retrieval: retrieves indicators (evidence: `main.py`)
- ChatBI system → Prompt builder: builds prompt (evidence: `main.py`)
- Prompt builder → Schema linker: requests schema (evidence: `prompt_builder.py`)
- Schema linker → Table retrieval: retrieves tables (evidence: `schema_linker.py`)
- Schema linker → Field matching: matches fields (evidence: `schema_linker.py`)
- Schema linker → Join resolution: resolves joins (evidence: `schema_linker.py`)
- Field matching → Table retrieval: uses retrieval (evidence: `field_matcher.py`)
- ChatBI system → LLM client: generates SQL (evidence: `main.py`)
- LLM client → LLM API: calls API (evidence: `llm_client.py`)
- ChatBI system → Database client: executes SQL (evidence: `main.py`)
- Database client → Query security: secures SQL (evidence: `database.py`)
- Database client → SQL database: queries (evidence: `README.md`)
- ChatBI system → Result formatter: formats results (evidence: `main.py`)
- Indicator retrieval → Indicator knowledge: uses definitions (evidence: `indicator_retriever.py`)
- Plan executor → Query decomposer: decomposes question (evidence: `README.md`)
- Plan executor → ChatBI system: executes steps (evidence: `agent_planner.py`)
- Plan executor → Report generator: generates report (evidence: `README.md`)
- Report generator → LLM client: requests summary (evidence: `report_generator.py`)
- Query decomposer → LLM client: generates plan (evidence: `query_decomposer.py`)
- Query decomposer → Prompt builder: uses schema (evidence: `query_decomposer.py`)
- Schema generator → SQL database: reads schema (evidence: `README.md`)
