# codergirl-cyber/tablyze architecture

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

- Interactive diagram: https://gitdiagram.com/codergirl-cyber/tablyze
- Repository: https://github.com/codergirl-cyber/tablyze

## Overview

Tablyze is a CSV-analysis web application. Users upload a dataset, receive statistical and visualization results, and can ask an AI agent questions grounded in analysis tools; reports can also be exported. The README documents the overall analysis and AI workflow, while excerpts and the source index support the main module relationships. The API route implementations and some frontend request wiring were not excerpted, so those links are left unverified rather than asserted.

Main entry points: [`app/page.tsx`](https://github.com/codergirl-cyber/tablyze/blob/main/app/page.tsx) (Dashboard page), [`backend/main.py`](https://github.com/codergirl-cyber/tablyze/blob/main/backend/main.py) (FastAPI service), [`app/components/FileCard.tsx`](https://github.com/codergirl-cyber/tablyze/blob/main/app/components/FileCard.tsx) (Upload controls), [`app/api/agent/investigate/route.ts`](https://github.com/codergirl-cyber/tablyze/blob/main/app/api/agent/investigate/route.ts) (Investigation route)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Dashboard"]
  node_dashboard["Dashboard page<br/>[page.tsx]"]
  node_upload_ui["Upload controls<br/>[FileCard.tsx]"]
  node_progress["Upload progress<br/>[UploadProgress.tsx]"]
  node_summary_ui["Summary cards<br/>[StatCard.tsx]"]
  node_missing_ui["Missing values chart"]
  node_types_ui["Data types chart"]
  node_correlation_ui["Correlation heatmap"]
  node_export_ui["PDF report export"]
  node_agent_ui["Question interface"]
  node_agent_client["Investigation client<br/>[agent.ts]"]
end

subgraph group_api["Web API"]
  node_upload_api["Upload route<br/>[route.ts]"]
  node_investigate_api["Investigation route<br/>[route.ts]"]
  node_backend_api["FastAPI service<br/>[main.py]"]
end

subgraph group_analysis["Dataset Analysis"]
  node_cache[("Analysis cache<br/>[cache.py]")]
  node_dataset_state[("Dataset state<br/>[state.py]")]
  node_analysis_core["Dataset statistics<br/>[analysis.py]"]
end

subgraph group_agent["AI Investigation"]
  node_agent_core["Investigation planner<br/>[agent.py]"]
  node_tools["Analysis tools<br/>[tools.py]"]
  node_llm_client["LLM provider client<br/>[llm_client.py]"]
  node_llm_provider["Provider interface<br/>[llm.py]"]
end

node_user(("Dataset user"))
node_llm_service(("LLM provider service"))

node_user -->|"uses"| node_dashboard
node_dashboard -->|"renders"| node_upload_ui
node_dashboard -->|"renders"| node_summary_ui
node_dashboard -->|"renders"| node_missing_ui
node_dashboard -->|"renders"| node_types_ui
node_dashboard -->|"renders"| node_correlation_ui
node_dashboard -->|"renders"| node_export_ui
node_upload_ui -->|"renders"| node_progress
node_upload_ui -.->|"submits CSV"| node_upload_api
node_upload_api -.->|"forwards upload"| node_backend_api
node_backend_api -->|"checks cache"| node_cache
node_backend_api -->|"analyzes dataset"| node_analysis_core
node_backend_api -->|"stores dataset"| node_dataset_state
node_backend_api -.->|"serves investigation"| node_investigate_api
node_dashboard -->|"renders"| node_agent_ui
node_agent_ui -->|"requests answer"| node_agent_client
node_agent_client -->|"posts question"| node_investigate_api
node_investigate_api -.->|"routes question"| node_backend_api
node_agent_core -->|"dispatches tools"| node_tools
node_tools -->|"uses analysis"| node_analysis_core
node_agent_core -->|"requests synthesis"| node_llm_client
node_llm_provider -->|"delegates calls"| node_llm_client
node_llm_client -->|"sends prompts"| node_llm_service
node_dashboard -->|"exports report"| node_export_ui

click node_dashboard "https://github.com/codergirl-cyber/tablyze/blob/main/app/page.tsx"
click node_upload_ui "https://github.com/codergirl-cyber/tablyze/blob/main/app/components/FileCard.tsx"
click node_progress "https://github.com/codergirl-cyber/tablyze/blob/main/app/components/UploadProgress.tsx"
click node_summary_ui "https://github.com/codergirl-cyber/tablyze/blob/main/app/components/StatCard.tsx"
click node_missing_ui "https://github.com/codergirl-cyber/tablyze/blob/main/app/components/MissingValuesBarChart.tsx"
click node_types_ui "https://github.com/codergirl-cyber/tablyze/blob/main/app/components/DataTypesPieChart.tsx"
click node_correlation_ui "https://github.com/codergirl-cyber/tablyze/blob/main/app/components/CorrelationHeatmap.tsx"
click node_export_ui "https://github.com/codergirl-cyber/tablyze/blob/main/app/components/ExportReportButton.tsx"
click node_upload_api "https://github.com/codergirl-cyber/tablyze/blob/main/app/api/upload/route.ts"
click node_investigate_api "https://github.com/codergirl-cyber/tablyze/blob/main/app/api/agent/investigate/route.ts"
click node_backend_api "https://github.com/codergirl-cyber/tablyze/blob/main/backend/main.py"
click node_cache "https://github.com/codergirl-cyber/tablyze/blob/main/backend/cache.py"
click node_dataset_state "https://github.com/codergirl-cyber/tablyze/blob/main/backend/agent/state.py"
click node_analysis_core "https://github.com/codergirl-cyber/tablyze/blob/main/backend/analysis.py"
click node_agent_ui "https://github.com/codergirl-cyber/tablyze/blob/main/app/components/DataAgentSection.tsx"
click node_agent_client "https://github.com/codergirl-cyber/tablyze/blob/main/app/lib/agent.ts"
click node_agent_core "https://github.com/codergirl-cyber/tablyze/blob/main/backend/agent/agent.py"
click node_tools "https://github.com/codergirl-cyber/tablyze/blob/main/backend/agent/tools.py"
click node_llm_client "https://github.com/codergirl-cyber/tablyze/blob/main/backend/agent/llm_client.py"
click node_llm_provider "https://github.com/codergirl-cyber/tablyze/blob/main/backend/agent/llm.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_upload_ui,node_progress,node_summary_ui,node_missing_ui,node_types_ui,node_correlation_ui,node_export_ui,node_agent_ui,node_agent_client,node_user toneBlue
class node_upload_api,node_investigate_api,node_backend_api toneAmber
class node_cache,node_dataset_state,node_analysis_core toneMint
class node_agent_core,node_tools,node_llm_client,node_llm_provider toneRose
class node_llm_service toneIndigo
```

## Components

### Dashboard

- [Dashboard page](https://github.com/codergirl-cyber/tablyze/blob/main/app/page.tsx): `app/page.tsx`
- [Upload controls](https://github.com/codergirl-cyber/tablyze/blob/main/app/components/FileCard.tsx): `app/components/FileCard.tsx`
- [Upload progress](https://github.com/codergirl-cyber/tablyze/blob/main/app/components/UploadProgress.tsx): `app/components/UploadProgress.tsx`
- [Summary cards](https://github.com/codergirl-cyber/tablyze/blob/main/app/components/StatCard.tsx): `app/components/StatCard.tsx`
- [Missing values chart](https://github.com/codergirl-cyber/tablyze/blob/main/app/components/MissingValuesBarChart.tsx): `app/components/MissingValuesBarChart.tsx`
- [Data types chart](https://github.com/codergirl-cyber/tablyze/blob/main/app/components/DataTypesPieChart.tsx): `app/components/DataTypesPieChart.tsx`
- [Correlation heatmap](https://github.com/codergirl-cyber/tablyze/blob/main/app/components/CorrelationHeatmap.tsx): `app/components/CorrelationHeatmap.tsx`
- [PDF report export](https://github.com/codergirl-cyber/tablyze/blob/main/app/components/ExportReportButton.tsx): `app/components/ExportReportButton.tsx`
- [Question interface](https://github.com/codergirl-cyber/tablyze/blob/main/app/components/DataAgentSection.tsx): `app/components/DataAgentSection.tsx`
- [Investigation client](https://github.com/codergirl-cyber/tablyze/blob/main/app/lib/agent.ts): `app/lib/agent.ts`

### Web API

- [Upload route](https://github.com/codergirl-cyber/tablyze/blob/main/app/api/upload/route.ts): `app/api/upload/route.ts`
- [Investigation route](https://github.com/codergirl-cyber/tablyze/blob/main/app/api/agent/investigate/route.ts): `app/api/agent/investigate/route.ts`
- [FastAPI service](https://github.com/codergirl-cyber/tablyze/blob/main/backend/main.py): `backend/main.py`

### Dataset Analysis

- [Analysis cache](https://github.com/codergirl-cyber/tablyze/blob/main/backend/cache.py): `backend/cache.py`
- [Dataset state](https://github.com/codergirl-cyber/tablyze/blob/main/backend/agent/state.py): `backend/agent/state.py`
- [Dataset statistics](https://github.com/codergirl-cyber/tablyze/blob/main/backend/analysis.py): `backend/analysis.py`

### AI Investigation

- [Investigation planner](https://github.com/codergirl-cyber/tablyze/blob/main/backend/agent/agent.py): `backend/agent/agent.py`
- [Analysis tools](https://github.com/codergirl-cyber/tablyze/blob/main/backend/agent/tools.py): `backend/agent/tools.py`
- [LLM provider client](https://github.com/codergirl-cyber/tablyze/blob/main/backend/agent/llm_client.py): `backend/agent/llm_client.py`
- [Provider interface](https://github.com/codergirl-cyber/tablyze/blob/main/backend/agent/llm.py): `backend/agent/llm.py`

### Other components

- **Dataset user**
- **LLM provider service**

## Connections

- Dataset user → Dashboard page: uses (evidence: `README.md`)
- Dashboard page → Upload controls: renders (evidence: `app/page.tsx`)
- Dashboard page → Summary cards: renders (evidence: `app/page.tsx`)
- Dashboard page → Missing values chart: renders (evidence: `app/page.tsx`)
- Dashboard page → Data types chart: renders (evidence: `app/page.tsx`)
- Dashboard page → Correlation heatmap: renders (evidence: `app/page.tsx`)
- Dashboard page → PDF report export: renders (evidence: `app/page.tsx`)
- Upload controls → Upload progress: renders (evidence: `app/components/FileCard.tsx`)
- Upload controls → Upload route: submits CSV
- Upload route → FastAPI service: forwards upload
- FastAPI service → Analysis cache: checks cache (evidence: `backend/main.py`)
- FastAPI service → Dataset statistics: analyzes dataset (evidence: `backend/main.py`)
- FastAPI service → Dataset state: stores dataset (evidence: `backend/main.py`)
- FastAPI service → Investigation route: serves investigation
- Dashboard page → Question interface: renders (evidence: `app/page.tsx`)
- Question interface → Investigation client: requests answer (evidence: `app/components/DataAgentSection.tsx`)
- Investigation client → Investigation route: posts question (evidence: `app/lib/agent.ts`)
- Investigation route → FastAPI service: routes question
- Investigation planner → Analysis tools: dispatches tools (evidence: `backend/agent/agent.py`)
- Analysis tools → Dataset statistics: uses analysis (evidence: `backend/agent/tools.py`)
- Investigation planner → LLM provider client: requests synthesis (evidence: `backend/agent/agent.py`)
- Provider interface → LLM provider client: delegates calls (evidence: `backend/agent/llm.py`)
- LLM provider client → LLM provider service: sends prompts (evidence: `backend/agent/llm_client.py`)
- Dashboard page → PDF report export: exports report (evidence: `app/components/ExportReportButton.tsx`)
