# s84v/ai-sql-analyst architecture

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

- Interactive diagram: https://gitdiagram.com/s84v/ai-sql-analyst
- Repository: https://github.com/s84v/ai-sql-analyst

## Overview

OlistIQ lets a user ask natural-language questions about the Olist dataset and receive a streamed, evidence-based answer. The main workflow runs from the React interface through the HTTP event stream to a LangGraph agent, which inspects schema and executes read-only SQL before generating an answer rendered as Markdown. A separate ingestion path loads Olist CSVs into PostgreSQL. The graph reflects shown imports and documented protocol boundaries; backend API wiring is supported by the source index, while unsampled implementation details are not inferred.

Main entry points: [`backend/src/ai_sql_analyst/api.py`](https://github.com/s84v/ai-sql-analyst/blob/main/backend/src/ai_sql_analyst/api.py) (HTTP API), [`frontend/src/App.tsx`](https://github.com/s84v/ai-sql-analyst/blob/main/frontend/src/App.tsx) (Question UI), [`backend/src/ai_sql_analyst/tools.py`](https://github.com/s84v/ai-sql-analyst/blob/main/backend/src/ai_sql_analyst/tools.py) (Agent tools), [`frontend/src/api.ts`](https://github.com/s84v/ai-sql-analyst/blob/main/frontend/src/api.ts) (SSE client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_app["Question UI<br/>[App.tsx]"]
  node_stream_client["SSE client<br/>[api.ts]"]
  node_answer_reveal["Answer reveal<br/>[AnswerReveal.tsx]"]
  node_markdown["Markdown renderer<br/>[MarkdownAnswer.tsx]"]
end

subgraph group_transport["Query transport"]
  node_api["HTTP API<br/>[api.py]"]
  node_event_translation["Event translator<br/>[streaming.py]"]
end

subgraph group_analysis["Analysis agent"]
  node_agent["Tool-calling agent<br/>[agent.py]"]
  node_model["DeepSeek model<br/>[model.py]"]
  node_tools["Agent tools<br/>[tools.py]"]
end

subgraph group_data["Data and SQL"]
  node_schema["Schema introspection<br/>[schema.py]"]
  node_query["Read-only SQL<br/>[query.py]"]
  node_db_config["DB connection<br/>[db.py]"]
  node_postgres[("PostgreSQL<br/>[schema.sql]")]
  node_ingest["CSV ingestion<br/>[ingest.py]"]
end

node_user(("Analyst"))
node_olist_csv["Olist CSV files"]
node_deepseek{{"DeepSeek API"}}

node_user -->|"asks question"| node_app
node_app -->|"streams question"| node_stream_client
node_stream_client -->|"POSTs query"| node_api
node_api -->|"streams events"| node_stream_client
node_app -->|"shows answer"| node_answer_reveal
node_answer_reveal -->|"renders markdown"| node_markdown
node_api -->|"builds model"| node_model
node_api -->|"runs agent"| node_agent
node_api -->|"translates events"| node_event_translation
node_model -.->|"calls provider"| node_deepseek
node_agent -->|"dispatches tools"| node_tools
node_tools -->|"gets schema"| node_schema
node_tools -->|"runs SQL"| node_query
node_schema -->|"connects via"| node_db_config
node_query -->|"connects via"| node_db_config
node_db_config -->|"opens connection"| node_postgres
node_ingest -->|"reads CSVs"| node_olist_csv
node_ingest -->|"loads tables"| node_postgres

click node_app "https://github.com/s84v/ai-sql-analyst/blob/main/frontend/src/App.tsx"
click node_stream_client "https://github.com/s84v/ai-sql-analyst/blob/main/frontend/src/api.ts"
click node_answer_reveal "https://github.com/s84v/ai-sql-analyst/blob/main/frontend/src/AnswerReveal.tsx"
click node_markdown "https://github.com/s84v/ai-sql-analyst/blob/main/frontend/src/MarkdownAnswer.tsx"
click node_api "https://github.com/s84v/ai-sql-analyst/blob/main/backend/src/ai_sql_analyst/api.py"
click node_event_translation "https://github.com/s84v/ai-sql-analyst/blob/main/backend/src/ai_sql_analyst/streaming.py"
click node_agent "https://github.com/s84v/ai-sql-analyst/blob/main/backend/src/ai_sql_analyst/agent.py"
click node_model "https://github.com/s84v/ai-sql-analyst/blob/main/backend/src/ai_sql_analyst/model.py"
click node_tools "https://github.com/s84v/ai-sql-analyst/blob/main/backend/src/ai_sql_analyst/tools.py"
click node_schema "https://github.com/s84v/ai-sql-analyst/blob/main/backend/src/ai_sql_analyst/schema.py"
click node_query "https://github.com/s84v/ai-sql-analyst/blob/main/backend/src/ai_sql_analyst/query.py"
click node_db_config "https://github.com/s84v/ai-sql-analyst/blob/main/backend/src/ai_sql_analyst/db.py"
click node_postgres "https://github.com/s84v/ai-sql-analyst/blob/main/backend/sql/schema.sql"
click node_ingest "https://github.com/s84v/ai-sql-analyst/blob/main/backend/src/ai_sql_analyst/ingest.py"
click node_olist_csv "https://github.com/s84v/ai-sql-analyst/tree/main/data/raw"

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_app,node_stream_client,node_answer_reveal,node_markdown toneBlue
class node_api,node_event_translation toneAmber
class node_agent,node_model,node_tools,node_deepseek toneMint
class node_schema,node_query,node_db_config,node_postgres,node_ingest toneRose
class node_user toneIndigo
class node_olist_csv toneTeal
```

## Components

### User interface

- [Question UI](https://github.com/s84v/ai-sql-analyst/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [SSE client](https://github.com/s84v/ai-sql-analyst/blob/main/frontend/src/api.ts): `frontend/src/api.ts`
- [Answer reveal](https://github.com/s84v/ai-sql-analyst/blob/main/frontend/src/AnswerReveal.tsx): `frontend/src/AnswerReveal.tsx`
- [Markdown renderer](https://github.com/s84v/ai-sql-analyst/blob/main/frontend/src/MarkdownAnswer.tsx): `frontend/src/MarkdownAnswer.tsx`

### Query transport

- [HTTP API](https://github.com/s84v/ai-sql-analyst/blob/main/backend/src/ai_sql_analyst/api.py): `backend/src/ai_sql_analyst/api.py`
- [Event translator](https://github.com/s84v/ai-sql-analyst/blob/main/backend/src/ai_sql_analyst/streaming.py): `backend/src/ai_sql_analyst/streaming.py`

### Analysis agent

- [Tool-calling agent](https://github.com/s84v/ai-sql-analyst/blob/main/backend/src/ai_sql_analyst/agent.py): `backend/src/ai_sql_analyst/agent.py`
- [DeepSeek model](https://github.com/s84v/ai-sql-analyst/blob/main/backend/src/ai_sql_analyst/model.py): `backend/src/ai_sql_analyst/model.py`
- [Agent tools](https://github.com/s84v/ai-sql-analyst/blob/main/backend/src/ai_sql_analyst/tools.py): `backend/src/ai_sql_analyst/tools.py`

### Data and SQL

- [Schema introspection](https://github.com/s84v/ai-sql-analyst/blob/main/backend/src/ai_sql_analyst/schema.py): `backend/src/ai_sql_analyst/schema.py`
- [Read-only SQL](https://github.com/s84v/ai-sql-analyst/blob/main/backend/src/ai_sql_analyst/query.py): `backend/src/ai_sql_analyst/query.py`
- [DB connection](https://github.com/s84v/ai-sql-analyst/blob/main/backend/src/ai_sql_analyst/db.py): `backend/src/ai_sql_analyst/db.py`
- [PostgreSQL](https://github.com/s84v/ai-sql-analyst/blob/main/backend/sql/schema.sql): `backend/sql/schema.sql`
- [CSV ingestion](https://github.com/s84v/ai-sql-analyst/blob/main/backend/src/ai_sql_analyst/ingest.py): `backend/src/ai_sql_analyst/ingest.py`

### Other components

- **Analyst**
- [Olist CSV files](https://github.com/s84v/ai-sql-analyst/tree/main/data/raw): `data/raw`
- **DeepSeek API**

## Connections

- Analyst → Question UI: asks question (evidence: `frontend/src/App.tsx`)
- Question UI → SSE client: streams question (evidence: `frontend/src/App.tsx`)
- SSE client → HTTP API: POSTs query (evidence: `frontend/src/api.ts`)
- HTTP API → SSE client: streams events (evidence: `frontend/src/api.ts`)
- Question UI → Answer reveal: shows answer (evidence: `frontend/src/App.tsx`)
- Answer reveal → Markdown renderer: renders markdown (evidence: `frontend/src/AnswerReveal.tsx`)
- HTTP API → DeepSeek model: builds model (evidence: `backend/src/ai_sql_analyst/api.py`)
- HTTP API → Tool-calling agent: runs agent (evidence: `backend/src/ai_sql_analyst/api.py`)
- HTTP API → Event translator: translates events (evidence: `backend/src/ai_sql_analyst/api.py`)
- DeepSeek model → DeepSeek API: calls provider
- Tool-calling agent → Agent tools: dispatches tools (evidence: `backend/src/ai_sql_analyst/agent.py`)
- Agent tools → Schema introspection: gets schema (evidence: `backend/src/ai_sql_analyst/tools.py`)
- Agent tools → Read-only SQL: runs SQL (evidence: `backend/src/ai_sql_analyst/tools.py`)
- Schema introspection → DB connection: connects via (evidence: `backend/src/ai_sql_analyst/schema.py`)
- Read-only SQL → DB connection: connects via (evidence: `backend/src/ai_sql_analyst/query.py`)
- DB connection → PostgreSQL: opens connection (evidence: `backend/src/ai_sql_analyst/db.py`)
- CSV ingestion → Olist CSV files: reads CSVs (evidence: `backend/src/ai_sql_analyst/ingest.py`)
- CSV ingestion → PostgreSQL: loads tables (evidence: `backend/src/ai_sql_analyst/ingest.py`)
