# phani-stack/baseinterface architecture

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

- Interactive diagram: https://gitdiagram.com/phani-stack/baseinterface
- Repository: https://github.com/phani-stack/baseinterface

## Overview

BaseInterface is a natural-language-to-MySQL chat application. A user asks a question in the browser; FastAPI sends it through a LangGraph workflow that refines the question, gathers database context, generates and executes SQL, then formats the result for the API response. A separate schema endpoint exposes table and column details. The sampled source confirms the workflow, API routes, and database/LLM calls; the README documents the browser interaction. The graph does not assume unshown provider or frontend wiring beyond that documentation.

Main entry points: [`app.py`](https://github.com/phani-stack/baseinterface/blob/main/app.py) (FastAPI Routes), [`main.py`](https://github.com/phani-stack/baseinterface/blob/main/main.py) (Workflow Graph), [`nodes/nodes.py`](https://github.com/phani-stack/baseinterface/blob/main/nodes/nodes.py) (Question Refinement), [`templates/index.html`](https://github.com/phani-stack/baseinterface/blob/main/templates/index.html) (Chat Page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Chat Interface"]
  node_chat["Chat Page<br/>[index.html]"]
end

subgraph group_api["HTTP API"]
  node_fastapi["FastAPI Routes<br/>[app.py]"]
  node_schema["Schema Endpoint Data<br/>[nodes.py]"]
end

subgraph group_workflow["Query Workflow"]
  node_graph["Workflow Graph<br/>[main.py]"]
  node_state["Workflow State<br/>[state.py]"]
  node_refine["Question Refinement<br/>[nodes.py]"]
  node_context["Database Context<br/>[nodes.py]"]
  node_generate["SQL Generation<br/>[nodes.py]"]
  node_execute["SQL Execution<br/>[nodes.py]"]
  node_present["Result Presentation<br/>[nodes.py]"]
end

subgraph group_integrations["External Systems"]
  node_llm{{"Groq LLM"}}
  node_mysql[("MySQL Database")]
end

node_user(("User"))

node_user -->|"asks question"| node_chat
node_chat -->|"submits query"| node_fastapi
node_fastapi -->|"renders page"| node_chat
node_fastapi -->|"runs workflow"| node_graph
node_fastapi -->|"serves schema"| node_schema
node_graph -->|"initializes state"| node_state
node_graph -->|"routes first"| node_refine
node_refine -->|"routes next"| node_context
node_context -->|"routes next"| node_generate
node_generate -->|"routes next"| node_execute
node_execute -->|"routes next"| node_present
node_refine -->|"invokes model"| node_llm
node_generate -->|"invokes model"| node_llm
node_present -->|"invokes model"| node_llm
node_context -->|"reads context"| node_mysql
node_execute -->|"runs SQL"| node_mysql
node_schema -->|"reads metadata"| node_mysql

click node_chat "https://github.com/phani-stack/baseinterface/blob/main/templates/index.html"
click node_fastapi "https://github.com/phani-stack/baseinterface/blob/main/app.py"
click node_graph "https://github.com/phani-stack/baseinterface/blob/main/main.py"
click node_state "https://github.com/phani-stack/baseinterface/blob/main/model/state.py"
click node_refine "https://github.com/phani-stack/baseinterface/blob/main/nodes/nodes.py"
click node_context "https://github.com/phani-stack/baseinterface/blob/main/nodes/nodes.py"
click node_generate "https://github.com/phani-stack/baseinterface/blob/main/nodes/nodes.py"
click node_execute "https://github.com/phani-stack/baseinterface/blob/main/nodes/nodes.py"
click node_present "https://github.com/phani-stack/baseinterface/blob/main/nodes/nodes.py"
click node_schema "https://github.com/phani-stack/baseinterface/blob/main/nodes/nodes.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_chat,node_user toneBlue
class node_fastapi,node_schema toneAmber
class node_graph,node_state,node_refine,node_context,node_generate,node_execute,node_present toneMint
class node_llm,node_mysql toneRose
```

## Components

### Chat Interface

- [Chat Page](https://github.com/phani-stack/baseinterface/blob/main/templates/index.html): `templates/index.html`

### HTTP API

- [FastAPI Routes](https://github.com/phani-stack/baseinterface/blob/main/app.py): `app.py`
- [Schema Endpoint Data](https://github.com/phani-stack/baseinterface/blob/main/nodes/nodes.py): `nodes/nodes.py`

### Query Workflow

- [Workflow Graph](https://github.com/phani-stack/baseinterface/blob/main/main.py): `main.py`
- [Workflow State](https://github.com/phani-stack/baseinterface/blob/main/model/state.py): `model/state.py`
- [Question Refinement](https://github.com/phani-stack/baseinterface/blob/main/nodes/nodes.py): `nodes/nodes.py`
- [Database Context](https://github.com/phani-stack/baseinterface/blob/main/nodes/nodes.py): `nodes/nodes.py`
- [SQL Generation](https://github.com/phani-stack/baseinterface/blob/main/nodes/nodes.py): `nodes/nodes.py`
- [SQL Execution](https://github.com/phani-stack/baseinterface/blob/main/nodes/nodes.py): `nodes/nodes.py`
- [Result Presentation](https://github.com/phani-stack/baseinterface/blob/main/nodes/nodes.py): `nodes/nodes.py`

### External Systems

- **Groq LLM**
- **MySQL Database**

### Other components

- **User**

## Connections

- User → Chat Page: asks question (evidence: `README.md`)
- Chat Page → FastAPI Routes: submits query (evidence: `README.md`)
- FastAPI Routes → Chat Page: renders page (evidence: `app.py`)
- FastAPI Routes → Workflow Graph: runs workflow (evidence: `app.py`)
- FastAPI Routes → Schema Endpoint Data: serves schema (evidence: `app.py`)
- Workflow Graph → Workflow State: initializes state (evidence: `main.py`)
- Workflow Graph → Question Refinement: routes first (evidence: `main.py`)
- Question Refinement → Database Context: routes next (evidence: `main.py`)
- Database Context → SQL Generation: routes next (evidence: `main.py`)
- SQL Generation → SQL Execution: routes next (evidence: `main.py`)
- SQL Execution → Result Presentation: routes next (evidence: `main.py`)
- Question Refinement → Groq LLM: invokes model (evidence: `nodes/nodes.py`)
- SQL Generation → Groq LLM: invokes model (evidence: `nodes/nodes.py`)
- Result Presentation → Groq LLM: invokes model (evidence: `nodes/nodes.py`)
- Database Context → MySQL Database: reads context (evidence: `nodes/nodes.py`)
- SQL Execution → MySQL Database: runs SQL (evidence: `nodes/nodes.py`)
- Schema Endpoint Data → MySQL Database: reads metadata (evidence: `nodes/nodes.py`)
