# eswarsainandan04/kelostats architecture

> Architecture diagram of the GitHub repository eswarsainandan04/kelostats, 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/eswarsainandan04/kelostats
- Repository: https://github.com/eswarsainandan04/kelostats

## Overview

KeloStats turns dashboard requests into analytics answers and editable presentations. Its principal workflow routes chat through a LangGraph orchestrator, which classifies intent, loads database schema, verifies the request, retrieves ambiguous entities, generates and repairs read-only SQL, then synthesizes an answer or plans and renders slides. Separate product branches manage database connections and schema, ingest/search documents, and edit or export workspaces. The README documents these stages and capabilities; sampled source confirms API routing, database/schema behavior, semantic search, and workspace rendering, but not every orchestration edge.

Main entry points: [`backend/workflow/orchestrator.py`](https://github.com/eswarsainandan04/kelostats/blob/main/backend/workflow/orchestrator.py) (Workflow graph), [`frontend/app/dashboard/workspace/ChatInterface.tsx`](https://github.com/eswarsainandan04/kelostats/blob/main/frontend/app/dashboard/workspace/ChatInterface.tsx) (Chat interface), [`backend/databases/database.py`](https://github.com/eswarsainandan04/kelostats/blob/main/backend/databases/database.py) (Database management), [`backend/main.py`](https://github.com/eswarsainandan04/kelostats/blob/main/backend/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web application"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_chatui["Chat interface<br/>[ChatInterface.tsx]"]
  node_frontendapi["API client<br/>[api.ts]"]
end

subgraph group_api["API and workflow"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_workflow["Workflow graph<br/>[orchestrator.py]"]
  node_classifier["Intent classifier"]
  node_verifier["Schema verifier"]
  node_retriever["Entity retrieval<br/>[retrival_agent.py]"]
  node_sqlwriter["SQL generation"]
  node_sqlrepair["SQL repair"]
  node_answer["Answer synthesis"]
  node_knowledge["Knowledge answers"]
  node_planner["Slide planning"]
end

subgraph group_data["Data sources"]
  node_dbapi["Database management<br/>[database.py]"]
  node_schema["Schema extraction<br/>[extractor.py]"]
  node_dbtools["SQL execution tools"]
  node_docupload["Document ingestion<br/>[document_upload.py]"]
  node_docprocess["Document processing"]
  node_search["Semantic search<br/>[semantic_search.py]"]
end

subgraph group_presentation["Presentation workspace"]
  node_pptgen["Slide compilation"]
  node_workspace["Workspace management"]
  node_editor["Slide editor<br/>[editor.py]"]
  node_render["Slide rendering<br/>[render_ppt.py]"]
end

subgraph group_identity["Identity and persistence"]
  node_auth["JWT verification<br/>[jwt_verifier.py]"]
end

node_user(("Analyst"))
node_llm{{"LLM service"}}
node_relational[("Connected databases")]
node_supabase[("Supabase storage")]
node_pgvector[("Document vector store")]

node_user -->|"uses"| node_dashboard
node_dashboard -->|"opens"| node_chatui
node_chatui -->|"submits query"| node_frontendapi
node_frontendapi -->|"sends request"| node_fastapi
node_fastapi -->|"verifies protected requests"| node_auth
node_fastapi -->|"routes workflow"| node_workflow
node_fastapi -->|"routes database requests"| node_dbapi
node_workflow -->|"classifies intent"| node_classifier
node_classifier -->|"requests classification"| node_llm
node_workflow -->|"loads schema"| node_schema
node_schema -->|"uses connection metadata"| node_dbapi
node_dbapi -->|"connects and reads schema"| node_relational
node_workflow -->|"checks query"| node_verifier
node_verifier -->|"requests verification"| node_llm
node_workflow -->|"retrieves entities"| node_retriever
node_retriever -->|"executes lookup SQL"| node_dbtools
node_workflow -->|"generates SQL"| node_sqlwriter
node_sqlwriter -->|"requests SQL"| node_llm
node_workflow -->|"executes SQL"| node_dbtools
node_dbtools -->|"runs read-only queries"| node_relational
node_workflow -->|"repairs failed SQL"| node_sqlrepair
node_sqlrepair -->|"requests repair"| node_llm
node_workflow -->|"synthesizes results"| node_answer
node_answer -->|"requests answer"| node_llm
node_docupload -->|"processes uploads"| node_docprocess
node_docprocess -->|"stores document chunks"| node_pgvector
node_workflow -->|"searches documents"| node_search
node_search -->|"retrieves relevant chunks"| node_pgvector
node_workflow -->|"answers from context"| node_knowledge
node_knowledge -->|"requests synthesis"| node_llm
node_workflow -->|"plans presentation"| node_planner
node_planner -->|"requests slide plan"| node_llm
node_workflow -->|"compiles slides"| node_pptgen
node_pptgen -->|"stores slide HTML"| node_supabase
node_workspace -->|"manages project files"| node_supabase
node_editor -->|"updates slide content"| node_supabase
node_render -->|"reads slide content"| node_supabase
node_chatui -->|"loads presentation"| node_workspace
node_chatui -->|"edits slides"| node_editor
node_chatui -->|"requests rendering"| node_render
node_dashboard -->|"manages connections"| node_dbapi
node_dbapi -->|"extracts schema"| node_schema

click node_dashboard "https://github.com/eswarsainandan04/kelostats/blob/main/frontend/app/dashboard/page.tsx"
click node_chatui "https://github.com/eswarsainandan04/kelostats/blob/main/frontend/app/dashboard/workspace/ChatInterface.tsx"
click node_frontendapi "https://github.com/eswarsainandan04/kelostats/blob/main/frontend/lib/api.ts"
click node_fastapi "https://github.com/eswarsainandan04/kelostats/blob/main/backend/main.py"
click node_workflow "https://github.com/eswarsainandan04/kelostats/blob/main/backend/workflow/orchestrator.py"
click node_classifier "https://github.com/eswarsainandan04/kelostats/blob/main/backend/Agents/query_classication_agent.py"
click node_verifier "https://github.com/eswarsainandan04/kelostats/blob/main/backend/Agents/query_verification_agent.py"
click node_retriever "https://github.com/eswarsainandan04/kelostats/blob/main/backend/Agents/retrival_agent.py"
click node_sqlwriter "https://github.com/eswarsainandan04/kelostats/blob/main/backend/Agents/sql_writer_agent.py"
click node_sqlrepair "https://github.com/eswarsainandan04/kelostats/blob/main/backend/Agents/sql_repair_agent.py"
click node_answer "https://github.com/eswarsainandan04/kelostats/blob/main/backend/Agents/answer_generator_agent.py"
click node_knowledge "https://github.com/eswarsainandan04/kelostats/blob/main/backend/Agents/knowledge_answer_agent.py"
click node_planner "https://github.com/eswarsainandan04/kelostats/blob/main/backend/Agents/slide_planning_agent.py"
click node_pptgen "https://github.com/eswarsainandan04/kelostats/blob/main/backend/Agents/ppt_generation_agent.py"
click node_dbapi "https://github.com/eswarsainandan04/kelostats/blob/main/backend/databases/database.py"
click node_schema "https://github.com/eswarsainandan04/kelostats/blob/main/backend/databases/schema_extraction/extractor.py"
click node_dbtools "https://github.com/eswarsainandan04/kelostats/tree/main/backend/databases/tools"
click node_docupload "https://github.com/eswarsainandan04/kelostats/blob/main/backend/documents/document_upload.py"
click node_docprocess "https://github.com/eswarsainandan04/kelostats/blob/main/backend/documents/document_processor.py"
click node_search "https://github.com/eswarsainandan04/kelostats/blob/main/backend/documents/semantic_search.py"
click node_workspace "https://github.com/eswarsainandan04/kelostats/blob/main/backend/workspace/manage_workspace.py"
click node_editor "https://github.com/eswarsainandan04/kelostats/blob/main/backend/workspace/editor.py"
click node_render "https://github.com/eswarsainandan04/kelostats/blob/main/backend/workspace/render_ppt.py"
click node_auth "https://github.com/eswarsainandan04/kelostats/blob/main/backend/auth/jwt_verifier.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_chatui,node_frontendapi toneBlue
class node_fastapi,node_workflow,node_classifier,node_verifier,node_retriever,node_sqlwriter,node_sqlrepair,node_answer,node_knowledge,node_planner,node_relational,node_supabase,node_pgvector toneAmber
class node_dbapi,node_schema,node_dbtools,node_docupload,node_docprocess,node_search toneMint
class node_pptgen,node_workspace,node_editor,node_render toneRose
class node_auth,node_user,node_llm toneIndigo
```

## Components

### Web application

- [Dashboard](https://github.com/eswarsainandan04/kelostats/blob/main/frontend/app/dashboard/page.tsx): `frontend/app/dashboard/page.tsx`
- [Chat interface](https://github.com/eswarsainandan04/kelostats/blob/main/frontend/app/dashboard/workspace/ChatInterface.tsx): `frontend/app/dashboard/workspace/ChatInterface.tsx`
- [API client](https://github.com/eswarsainandan04/kelostats/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`

### API and workflow

- [FastAPI app](https://github.com/eswarsainandan04/kelostats/blob/main/backend/main.py): `backend/main.py`
- [Workflow graph](https://github.com/eswarsainandan04/kelostats/blob/main/backend/workflow/orchestrator.py): `backend/workflow/orchestrator.py`
- [Intent classifier](https://github.com/eswarsainandan04/kelostats/blob/main/backend/Agents/query_classication_agent.py): `backend/Agents/query_classication_agent.py`
- [Schema verifier](https://github.com/eswarsainandan04/kelostats/blob/main/backend/Agents/query_verification_agent.py): `backend/Agents/query_verification_agent.py`
- [Entity retrieval](https://github.com/eswarsainandan04/kelostats/blob/main/backend/Agents/retrival_agent.py): `backend/Agents/retrival_agent.py`
- [SQL generation](https://github.com/eswarsainandan04/kelostats/blob/main/backend/Agents/sql_writer_agent.py): `backend/Agents/sql_writer_agent.py`
- [SQL repair](https://github.com/eswarsainandan04/kelostats/blob/main/backend/Agents/sql_repair_agent.py): `backend/Agents/sql_repair_agent.py`
- [Answer synthesis](https://github.com/eswarsainandan04/kelostats/blob/main/backend/Agents/answer_generator_agent.py): `backend/Agents/answer_generator_agent.py`
- [Knowledge answers](https://github.com/eswarsainandan04/kelostats/blob/main/backend/Agents/knowledge_answer_agent.py): `backend/Agents/knowledge_answer_agent.py`
- [Slide planning](https://github.com/eswarsainandan04/kelostats/blob/main/backend/Agents/slide_planning_agent.py): `backend/Agents/slide_planning_agent.py`

### Data sources

- [Database management](https://github.com/eswarsainandan04/kelostats/blob/main/backend/databases/database.py): `backend/databases/database.py`
- [Schema extraction](https://github.com/eswarsainandan04/kelostats/blob/main/backend/databases/schema_extraction/extractor.py): `backend/databases/schema_extraction/extractor.py`
- [SQL execution tools](https://github.com/eswarsainandan04/kelostats/tree/main/backend/databases/tools): `backend/databases/tools`
- [Document ingestion](https://github.com/eswarsainandan04/kelostats/blob/main/backend/documents/document_upload.py): `backend/documents/document_upload.py`
- [Document processing](https://github.com/eswarsainandan04/kelostats/blob/main/backend/documents/document_processor.py): `backend/documents/document_processor.py`
- [Semantic search](https://github.com/eswarsainandan04/kelostats/blob/main/backend/documents/semantic_search.py): `backend/documents/semantic_search.py`

### Presentation workspace

- [Slide compilation](https://github.com/eswarsainandan04/kelostats/blob/main/backend/Agents/ppt_generation_agent.py): `backend/Agents/ppt_generation_agent.py`
- [Workspace management](https://github.com/eswarsainandan04/kelostats/blob/main/backend/workspace/manage_workspace.py): `backend/workspace/manage_workspace.py`
- [Slide editor](https://github.com/eswarsainandan04/kelostats/blob/main/backend/workspace/editor.py): `backend/workspace/editor.py`
- [Slide rendering](https://github.com/eswarsainandan04/kelostats/blob/main/backend/workspace/render_ppt.py): `backend/workspace/render_ppt.py`

### Identity and persistence

- [JWT verification](https://github.com/eswarsainandan04/kelostats/blob/main/backend/auth/jwt_verifier.py): `backend/auth/jwt_verifier.py`

### Other components

- **Analyst**
- **LLM service**
- **Connected databases**
- **Supabase storage**
- **Document vector store**

## Connections

- Analyst → Dashboard: uses
- Dashboard → Chat interface: opens
- Chat interface → API client: submits query
- API client → FastAPI app: sends request
- FastAPI app → JWT verification: verifies protected requests
- FastAPI app → Workflow graph: routes workflow
- FastAPI app → Database management: routes database requests
- Workflow graph → Intent classifier: classifies intent
- Intent classifier → LLM service: requests classification
- Workflow graph → Schema extraction: loads schema
- Schema extraction → Database management: uses connection metadata
- Database management → Connected databases: connects and reads schema
- Workflow graph → Schema verifier: checks query
- Schema verifier → LLM service: requests verification
- Workflow graph → Entity retrieval: retrieves entities
- Entity retrieval → SQL execution tools: executes lookup SQL
- Workflow graph → SQL generation: generates SQL
- SQL generation → LLM service: requests SQL
- Workflow graph → SQL execution tools: executes SQL
- SQL execution tools → Connected databases: runs read-only queries
- Workflow graph → SQL repair: repairs failed SQL
- SQL repair → LLM service: requests repair
- Workflow graph → Answer synthesis: synthesizes results
- Answer synthesis → LLM service: requests answer
- Document ingestion → Document processing: processes uploads
- Document processing → Document vector store: stores document chunks
- Workflow graph → Semantic search: searches documents
- Semantic search → Document vector store: retrieves relevant chunks
- Workflow graph → Knowledge answers: answers from context
- Knowledge answers → LLM service: requests synthesis
- Workflow graph → Slide planning: plans presentation
- Slide planning → LLM service: requests slide plan
- Workflow graph → Slide compilation: compiles slides
- Slide compilation → Supabase storage: stores slide HTML
- Workspace management → Supabase storage: manages project files
- Slide editor → Supabase storage: updates slide content
- Slide rendering → Supabase storage: reads slide content
- Chat interface → Workspace management: loads presentation
- Chat interface → Slide editor: edits slides
- Chat interface → Slide rendering: requests rendering
- Dashboard → Database management: manages connections
- Database management → Schema extraction: extracts schema