# rithik-31-c/doxa---business-intelligence-agents architecture

> Architecture diagram of the GitHub repository rithik-31-c/doxa---business-intelligence-agents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rithik-31-c/doxa---business-intelligence-agents
- Repository: https://github.com/rithik-31-c/doxa---business-intelligence-agents

## Overview

DOXA is a CSV-based business intelligence investigation app: users upload a dataset, ask a natural-language question, and receive deterministic evidence plus an AI-written explanation. The documented main path profiles and semantically interprets uploaded data, plans and validates an analysis, executes it, then explains the evidence. The dashboard presents dataset details and results. A separate shop-agent/tool capability is represented from source-index references; its entry point is not established by the excerpts. Some frontend-to-backend wiring is likewise not shown.

Main entry points: [`server/agents/shopAgent.js`](https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/agents/shopAgent.js) (Shop Agent), [`server/controllers/uploadController.js`](https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/controllers/uploadController.js) (Upload Controller), [`server/services/shopAnalysisService.js`](https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/services/shopAnalysisService.js) (Investigation Service), [`server/agents/schemaUnderstanding.js`](https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/agents/schemaUnderstanding.js) (Schema Understanding)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User Interface"]
  node_landing["Landing Page<br/>[DoxaLanding.jsx]"]
  node_dashboard["Investigation Dashboard<br/>[Dashboard.jsx]"]
  node_api["API Client<br/>[api.js]"]
end

subgraph group_ingest["Dataset Understanding"]
  node_upload["Upload Controller"]
  node_csv["CSV Parser<br/>[csvParser.js]"]
  node_profiler["Dataset Profiler<br/>[datasetProfiler.js]"]
  node_schema["Schema Understanding"]
  node_embedding["Embedding Client<br/>[embeddingClient.js]"]
  node_vector["Vector Utilities<br/>[vectorUtils.js]"]
  node_dataset[("Current Dataset<br/>[datasetService.js]")]
end

subgraph group_investigation["Investigation Runtime"]
  node_routes["Shop Routes<br/>[shopRoutes.js]"]
  node_shopcontroller["Analysis Controller<br/>[shopController.js]"]
  node_service["Investigation Service"]
  node_planner["Query Planner<br/>[queryPlanner.js]"]
  node_engine["Analysis Engine<br/>[analysisEngine.js]"]
  node_llama["Llama Client<br/>[llamaClient.js]"]
end

subgraph group_agents["Shop Agent Tools"]
  node_shopagent["Shop Agent<br/>[shopAgent.js]"]
  node_selector["Tool Selector<br/>[toolSelector.js]"]
  node_sales["Sales Tool<br/>[salesTool.js]"]
  node_inventory["Inventory Tool<br/>[inventoryTool.js]"]
  node_trend["Trend Tool<br/>[trendTool.js]"]
  node_calculator["Calculator Tool<br/>[calculatorTool.js]"]
end

node_user(("Business User"))

node_user -->|"starts investigation"| node_landing
node_user -->|"asks questions"| node_dashboard
node_dashboard -.->|"requests data"| node_api
node_routes -->|"routes uploads"| node_upload
node_routes -->|"routes analysis"| node_shopcontroller
node_upload -->|"reads CSV"| node_csv
node_upload -->|"profiles rows"| node_profiler
node_upload -->|"interprets columns"| node_schema
node_schema -->|"creates embeddings"| node_embedding
node_schema -->|"uses similarity"| node_vector
node_upload -->|"stores dataset"| node_dataset
node_shopcontroller -->|"analyzes request"| node_service
node_service -->|"reads current data"| node_dataset
node_service -->|"plans question"| node_planner
node_planner -->|"requests plan"| node_llama
node_service -->|"executes plan"| node_engine
node_service -->|"requests explanation"| node_llama
node_shopagent -->|"reads CSV"| node_csv
node_shopagent -->|"selects tools"| node_selector
node_selector -->|"creates embeddings"| node_embedding
node_selector -->|"uses similarity"| node_vector
node_shopagent -->|"uses tool"| node_sales
node_shopagent -->|"uses tool"| node_inventory
node_shopagent -->|"uses tool"| node_trend
node_shopagent -->|"uses tool"| node_calculator
node_shopagent -->|"requests explanation"| node_llama
node_shopagent -->|"reads dataset"| node_dataset

click node_landing "https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/client/src/pages/DoxaLanding.jsx"
click node_dashboard "https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/client/src/pages/Dashboard.jsx"
click node_api "https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/client/src/services/api.js"
click node_routes "https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/routes/shopRoutes.js"
click node_upload "https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/controllers/uploadController.js"
click node_shopcontroller "https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/controllers/shopController.js"
click node_csv "https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/utils/csvParser.js"
click node_profiler "https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/agents/datasetProfiler.js"
click node_schema "https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/agents/schemaUnderstanding.js"
click node_embedding "https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/ai/embeddingClient.js"
click node_vector "https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/utils/vectorUtils.js"
click node_dataset "https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/services/datasetService.js"
click node_service "https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/services/shopAnalysisService.js"
click node_planner "https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/agents/queryPlanner.js"
click node_engine "https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/analysis/analysisEngine.js"
click node_llama "https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/ai/llamaClient.js"
click node_shopagent "https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/agents/shopAgent.js"
click node_selector "https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/agents/toolSelector.js"
click node_sales "https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/tools/salesTool.js"
click node_inventory "https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/tools/inventoryTool.js"
click node_trend "https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/tools/trendTool.js"
click node_calculator "https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/tools/calculatorTool.js"

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_landing,node_dashboard,node_api,node_user toneBlue
class node_upload,node_csv,node_profiler,node_schema,node_embedding,node_vector,node_dataset toneAmber
class node_routes,node_shopcontroller,node_service,node_planner,node_engine,node_llama toneMint
class node_shopagent,node_selector,node_sales,node_inventory,node_trend,node_calculator toneRose
```

## Components

### User Interface

- [Landing Page](https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/client/src/pages/DoxaLanding.jsx): `client/src/pages/DoxaLanding.jsx`
- [Investigation Dashboard](https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/client/src/pages/Dashboard.jsx): `client/src/pages/Dashboard.jsx`
- [API Client](https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/client/src/services/api.js): `client/src/services/api.js`

### Dataset Understanding

- [Upload Controller](https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/controllers/uploadController.js): `server/controllers/uploadController.js`
- [CSV Parser](https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/utils/csvParser.js): `server/utils/csvParser.js`
- [Dataset Profiler](https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/agents/datasetProfiler.js): `server/agents/datasetProfiler.js`
- [Schema Understanding](https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/agents/schemaUnderstanding.js): `server/agents/schemaUnderstanding.js`
- [Embedding Client](https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/ai/embeddingClient.js): `server/ai/embeddingClient.js`
- [Vector Utilities](https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/utils/vectorUtils.js): `server/utils/vectorUtils.js`
- [Current Dataset](https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/services/datasetService.js): `server/services/datasetService.js`

### Investigation Runtime

- [Shop Routes](https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/routes/shopRoutes.js): `server/routes/shopRoutes.js`
- [Analysis Controller](https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/controllers/shopController.js): `server/controllers/shopController.js`
- [Investigation Service](https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/services/shopAnalysisService.js): `server/services/shopAnalysisService.js`
- [Query Planner](https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/agents/queryPlanner.js): `server/agents/queryPlanner.js`
- [Analysis Engine](https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/analysis/analysisEngine.js): `server/analysis/analysisEngine.js`
- [Llama Client](https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/ai/llamaClient.js): `server/ai/llamaClient.js`

### Shop Agent Tools

- [Shop Agent](https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/agents/shopAgent.js): `server/agents/shopAgent.js`
- [Tool Selector](https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/agents/toolSelector.js): `server/agents/toolSelector.js`
- [Sales Tool](https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/tools/salesTool.js): `server/tools/salesTool.js`
- [Inventory Tool](https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/tools/inventoryTool.js): `server/tools/inventoryTool.js`
- [Trend Tool](https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/tools/trendTool.js): `server/tools/trendTool.js`
- [Calculator Tool](https://github.com/rithik-31-c/doxa---business-intelligence-agents/blob/main/server/tools/calculatorTool.js): `server/tools/calculatorTool.js`

### Other components

- **Business User**

## Connections

- Business User → Landing Page: starts investigation
- Business User → Investigation Dashboard: asks questions
- Investigation Dashboard → API Client: requests data (evidence: `client/src/pages/Dashboard.jsx`)
- Shop Routes → Upload Controller: routes uploads (evidence: `server/routes/shopRoutes.js`)
- Shop Routes → Analysis Controller: routes analysis (evidence: `server/routes/shopRoutes.js`)
- Upload Controller → CSV Parser: reads CSV (evidence: `server/controllers/uploadController.js`)
- Upload Controller → Dataset Profiler: profiles rows (evidence: `server/controllers/uploadController.js`)
- Upload Controller → Schema Understanding: interprets columns (evidence: `server/controllers/uploadController.js`)
- Schema Understanding → Embedding Client: creates embeddings (evidence: `server/agents/schemaUnderstanding.js`)
- Schema Understanding → Vector Utilities: uses similarity (evidence: `server/agents/schemaUnderstanding.js`)
- Upload Controller → Current Dataset: stores dataset (evidence: `server/controllers/uploadController.js`)
- Analysis Controller → Investigation Service: analyzes request (evidence: `server/controllers/shopController.js`)
- Investigation Service → Current Dataset: reads current data (evidence: `server/services/shopAnalysisService.js`)
- Investigation Service → Query Planner: plans question (evidence: `server/services/shopAnalysisService.js`)
- Query Planner → Llama Client: requests plan (evidence: `server/agents/queryPlanner.js`)
- Investigation Service → Analysis Engine: executes plan (evidence: `server/services/shopAnalysisService.js`)
- Investigation Service → Llama Client: requests explanation (evidence: `server/services/shopAnalysisService.js`)
- Shop Agent → CSV Parser: reads CSV (evidence: `server/agents/shopAgent.js`)
- Shop Agent → Tool Selector: selects tools (evidence: `server/agents/shopAgent.js`)
- Tool Selector → Embedding Client: creates embeddings (evidence: `server/agents/toolSelector.js`)
- Tool Selector → Vector Utilities: uses similarity (evidence: `server/agents/toolSelector.js`)
- Shop Agent → Sales Tool: uses tool (evidence: `server/agents/shopAgent.js`)
- Shop Agent → Inventory Tool: uses tool (evidence: `server/agents/shopAgent.js`)
- Shop Agent → Trend Tool: uses tool (evidence: `server/agents/shopAgent.js`)
- Shop Agent → Calculator Tool: uses tool (evidence: `server/agents/shopAgent.js`)
- Shop Agent → Llama Client: requests explanation (evidence: `server/agents/shopAgent.js`)
- Shop Agent → Current Dataset: reads dataset (evidence: `server/agents/shopAgent.js`)
