# kesavaai/vecturabi architecture

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

- Interactive diagram: https://gitdiagram.com/kesavaai/vecturabi
- Repository: https://github.com/kesavaai/vecturabi

## Overview

VecturaBI turns conversational questions into validated, typed query plans, executes them over in-memory Polars data, and presents results with visualizations, explanations, and audit details. The agent coordinates cache lookup, schema-aware parsing, validation, execution, and downstream analytics; the UI renders the returned result and supporting outputs. README capabilities are included where documented, but unsampled implementation details are represented only at their existing enclosing paths.

Main entry points: [`core/agent/nodes.py`](https://github.com/kesavaai/vecturabi/blob/main/core/agent/nodes.py) (Agent nodes), [`app/main.py`](https://github.com/kesavaai/vecturabi/blob/main/app/main.py) (BI dashboard), [`core/data/loader.py`](https://github.com/kesavaai/vecturabi/blob/main/core/data/loader.py) (Data loader), [`app/components/chat.py`](https://github.com/kesavaai/vecturabi/blob/main/app/components/chat.py) (Chat interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_dashboard["BI dashboard<br/>[main.py]"]
  node_chat["Chat interface<br/>[chat.py]"]
  node_results["Result views<br/>[data_table.py]"]
  node_inspector["Execution inspector<br/>[inspector.py]"]
end

subgraph group_agent["Agent workflow"]
  node_agent_graph["Agent graph<br/>[graph.py]"]
  node_agent_nodes["Agent nodes<br/>[nodes.py]"]
  node_parser["Query parser"]
  node_cache[("Semantic cache<br/>[semantic_cache.py]")]
end

subgraph group_query["Query execution"]
  node_loader["Data loader<br/>[loader.py]"]
  node_dataset[("Sales dataset")]
  node_ast_models["Query AST<br/>[models.py]"]
  node_validator["AST validator<br/>[validator.py]"]
  node_compiler["Polars compiler<br/>[compiler.py]"]
  node_sql_translator["SQL transparency<br/>[sql_translator.py]"]
end

subgraph group_intelligence["Analysis outputs"]
  node_analytics["Analytics coordinator<br/>[nodes.py]"]
  node_anomalies["Anomaly detection<br/>[anomalies.py]"]
  node_diagnostics["Diagnostics<br/>[diagnostic.py]"]
  node_insights["Executive insights<br/>[insights.py]"]
  node_recommendations["Next analysis<br/>[recommender.py]"]
  node_briefing["Briefing generator"]
  node_visualizer["Chart engine<br/>[chart_engine.py]"]
end

node_user(("BI user"))

node_user -->|"asks question"| node_chat
node_chat -->|"submits query"| node_dashboard
node_dashboard -->|"invokes agent"| node_agent_graph
node_agent_graph -->|"dispatches steps"| node_agent_nodes
node_agent_nodes -->|"reads schema"| node_loader
node_agent_nodes -->|"looks up plan"| node_cache
node_agent_nodes -->|"parses query"| node_parser
node_agent_nodes -->|"validates AST"| node_validator
node_agent_nodes -->|"executes query"| node_compiler
node_agent_nodes -->|"translates AST"| node_sql_translator
node_loader -->|"loads data"| node_dataset
node_loader -->|"provides schema"| node_agent_nodes
node_parser -->|"builds AST"| node_ast_models
node_validator -->|"sanitizes AST"| node_ast_models
node_agent_nodes -->|"stores plan"| node_cache
node_compiler -->|"reads lazy data"| node_loader
node_agent_nodes -->|"analyzes results"| node_analytics
node_analytics -->|"detects anomalies"| node_anomalies
node_analytics -->|"diagnoses issues"| node_diagnostics
node_analytics -->|"summarizes results"| node_insights
node_analytics -->|"suggests analyses"| node_recommendations
node_analytics -->|"generates briefing"| node_briefing
node_dashboard -->|"builds charts"| node_visualizer
node_dashboard -->|"renders results"| node_results
node_dashboard -->|"renders audit"| node_inspector

click node_dashboard "https://github.com/kesavaai/vecturabi/blob/main/app/main.py"
click node_chat "https://github.com/kesavaai/vecturabi/blob/main/app/components/chat.py"
click node_results "https://github.com/kesavaai/vecturabi/blob/main/app/components/data_table.py"
click node_inspector "https://github.com/kesavaai/vecturabi/blob/main/app/components/inspector.py"
click node_agent_graph "https://github.com/kesavaai/vecturabi/blob/main/core/agent/graph.py"
click node_agent_nodes "https://github.com/kesavaai/vecturabi/blob/main/core/agent/nodes.py"
click node_parser "https://github.com/kesavaai/vecturabi/blob/main/core/agent/prompt_templates.py"
click node_cache "https://github.com/kesavaai/vecturabi/blob/main/core/cache/semantic_cache.py"
click node_loader "https://github.com/kesavaai/vecturabi/blob/main/core/data/loader.py"
click node_dataset "https://github.com/kesavaai/vecturabi/blob/main/data/enterprise_sales_data.parquet"
click node_ast_models "https://github.com/kesavaai/vecturabi/blob/main/core/ast_engine/models.py"
click node_validator "https://github.com/kesavaai/vecturabi/blob/main/core/ast_engine/validator.py"
click node_compiler "https://github.com/kesavaai/vecturabi/blob/main/core/ast_engine/compiler.py"
click node_sql_translator "https://github.com/kesavaai/vecturabi/blob/main/core/ast_engine/sql_translator.py"
click node_analytics "https://github.com/kesavaai/vecturabi/blob/main/core/agent/nodes.py"
click node_anomalies "https://github.com/kesavaai/vecturabi/blob/main/core/analytics/anomalies.py"
click node_diagnostics "https://github.com/kesavaai/vecturabi/blob/main/core/analytics/diagnostic.py"
click node_insights "https://github.com/kesavaai/vecturabi/blob/main/core/analytics/insights.py"
click node_recommendations "https://github.com/kesavaai/vecturabi/blob/main/core/analytics/recommender.py"
click node_briefing "https://github.com/kesavaai/vecturabi/blob/main/core/analytics/briefing_generator.py"
click node_visualizer "https://github.com/kesavaai/vecturabi/blob/main/core/visualizer/chart_engine.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_dashboard,node_chat,node_results,node_inspector,node_user toneBlue
class node_agent_graph,node_agent_nodes,node_parser,node_cache toneAmber
class node_loader,node_dataset,node_ast_models,node_validator,node_compiler,node_sql_translator toneMint
class node_analytics,node_anomalies,node_diagnostics,node_insights,node_recommendations,node_briefing,node_visualizer toneRose
```

## Components

### User experience

- [BI dashboard](https://github.com/kesavaai/vecturabi/blob/main/app/main.py): `app/main.py`
- [Chat interface](https://github.com/kesavaai/vecturabi/blob/main/app/components/chat.py): `app/components/chat.py`
- [Result views](https://github.com/kesavaai/vecturabi/blob/main/app/components/data_table.py): `app/components/data_table.py`
- [Execution inspector](https://github.com/kesavaai/vecturabi/blob/main/app/components/inspector.py): `app/components/inspector.py`

### Agent workflow

- [Agent graph](https://github.com/kesavaai/vecturabi/blob/main/core/agent/graph.py): `core/agent/graph.py`
- [Agent nodes](https://github.com/kesavaai/vecturabi/blob/main/core/agent/nodes.py): `core/agent/nodes.py`
- [Query parser](https://github.com/kesavaai/vecturabi/blob/main/core/agent/prompt_templates.py): `core/agent/prompt_templates.py`
- [Semantic cache](https://github.com/kesavaai/vecturabi/blob/main/core/cache/semantic_cache.py): `core/cache/semantic_cache.py`

### Query execution

- [Data loader](https://github.com/kesavaai/vecturabi/blob/main/core/data/loader.py): `core/data/loader.py`
- [Sales dataset](https://github.com/kesavaai/vecturabi/blob/main/data/enterprise_sales_data.parquet): `data/enterprise_sales_data.parquet`
- [Query AST](https://github.com/kesavaai/vecturabi/blob/main/core/ast_engine/models.py): `core/ast_engine/models.py`
- [AST validator](https://github.com/kesavaai/vecturabi/blob/main/core/ast_engine/validator.py): `core/ast_engine/validator.py`
- [Polars compiler](https://github.com/kesavaai/vecturabi/blob/main/core/ast_engine/compiler.py): `core/ast_engine/compiler.py`
- [SQL transparency](https://github.com/kesavaai/vecturabi/blob/main/core/ast_engine/sql_translator.py): `core/ast_engine/sql_translator.py`

### Analysis outputs

- [Analytics coordinator](https://github.com/kesavaai/vecturabi/blob/main/core/agent/nodes.py): `core/agent/nodes.py`
- [Anomaly detection](https://github.com/kesavaai/vecturabi/blob/main/core/analytics/anomalies.py): `core/analytics/anomalies.py`
- [Diagnostics](https://github.com/kesavaai/vecturabi/blob/main/core/analytics/diagnostic.py): `core/analytics/diagnostic.py`
- [Executive insights](https://github.com/kesavaai/vecturabi/blob/main/core/analytics/insights.py): `core/analytics/insights.py`
- [Next analysis](https://github.com/kesavaai/vecturabi/blob/main/core/analytics/recommender.py): `core/analytics/recommender.py`
- [Briefing generator](https://github.com/kesavaai/vecturabi/blob/main/core/analytics/briefing_generator.py): `core/analytics/briefing_generator.py`
- [Chart engine](https://github.com/kesavaai/vecturabi/blob/main/core/visualizer/chart_engine.py): `core/visualizer/chart_engine.py`

### Other components

- **BI user**

## Connections

- BI user → Chat interface: asks question
- Chat interface → BI dashboard: submits query
- BI dashboard → Agent graph: invokes agent
- Agent graph → Agent nodes: dispatches steps
- Agent nodes → Data loader: reads schema
- Agent nodes → Semantic cache: looks up plan
- Agent nodes → Query parser: parses query
- Agent nodes → AST validator: validates AST
- Agent nodes → Polars compiler: executes query
- Agent nodes → SQL transparency: translates AST
- Data loader → Sales dataset: loads data
- Data loader → Agent nodes: provides schema
- Query parser → Query AST: builds AST
- AST validator → Query AST: sanitizes AST
- Agent nodes → Semantic cache: stores plan
- Polars compiler → Data loader: reads lazy data
- Agent nodes → Analytics coordinator: analyzes results
- Analytics coordinator → Anomaly detection: detects anomalies
- Analytics coordinator → Diagnostics: diagnoses issues
- Analytics coordinator → Executive insights: summarizes results
- Analytics coordinator → Next analysis: suggests analyses
- Analytics coordinator → Briefing generator: generates briefing
- BI dashboard → Chart engine: builds charts
- BI dashboard → Result views: renders results
- BI dashboard → Execution inspector: renders audit