# shravantv/moviebot architecture

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

## Overview

MovieBot lets a user ask movie questions in a Streamlit chat, sends recent conversation history to a FastAPI endpoint, and returns an agent-generated answer. The backend orchestrates SQL generation, execution, and—if needed—query repair before responding. MovieLens CSV data initializes SQLite; the backend introspects and queries that database. The README also documents Groq-hosted inference and optional LangSmith tracing. Tool-to-storage and model calls are visible in excerpts; database initialization and tracing relationships are documented, but their deployment wiring is not independently verified here.

Main entry points: [`backend/app/main.py`](https://github.com/shravantv/moviebot/blob/main/backend/app/main.py) (Query API and agent), [`backend/app/tools/generate_sql.py`](https://github.com/shravantv/moviebot/blob/main/backend/app/tools/generate_sql.py) (SQL generation), [`webapp/app.py`](https://github.com/shravantv/moviebot/blob/main/webapp/app.py) (Streamlit chat), [`backend/app/db_tool.py`](https://github.com/shravantv/moviebot/blob/main/backend/app/db_tool.py) (Database access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Chat interface"]
  node_webapp["Streamlit chat<br/>[app.py]"]
end

subgraph group_backend["Backend orchestration"]
  node_api["Query API and agent<br/>[main.py]"]
  node_generate["SQL generation<br/>[generate_sql.py]"]
  node_execute["SQL execution"]
  node_repair["Query repair<br/>[fix_sql_query.py]"]
end

subgraph group_data["SQL and data"]
  node_dbtool["Database access<br/>[db_tool.py]"]
  node_sqlite[("SQLite movie database")]
end

subgraph group_setup["Database initialization"]
  node_dbmanager["CSV import and schema<br/>[db_manager.py]"]
  node_movielens["MovieLens CSV data"]
end

node_user(("MovieBot user"))
node_groq{{"Groq model service"}}
node_langsmith{{"LangSmith tracing"}}

node_user -->|"asks question"| node_webapp
node_webapp -->|"posts history"| node_api
node_api -->|"returns answer"| node_webapp
node_api -->|"dispatches tools"| node_generate
node_api -->|"dispatches tools"| node_execute
node_api -->|"dispatches tools"| node_repair
node_generate -->|"reads schema"| node_dbtool
node_execute -->|"executes query"| node_dbtool
node_generate -->|"requests SQL"| node_groq
node_repair -->|"requests correction"| node_groq
node_dbtool -->|"reads schema and rows"| node_sqlite
node_dbmanager -->|"imports CSV files"| node_movielens
node_dbmanager -.->|"initializes tables"| node_sqlite
node_api -.->|"traces requests"| node_langsmith

click node_webapp "https://github.com/shravantv/moviebot/blob/main/webapp/app.py"
click node_api "https://github.com/shravantv/moviebot/blob/main/backend/app/main.py"
click node_generate "https://github.com/shravantv/moviebot/blob/main/backend/app/tools/generate_sql.py"
click node_execute "https://github.com/shravantv/moviebot/blob/main/backend/app/tools/execute_sql_query.py"
click node_repair "https://github.com/shravantv/moviebot/blob/main/backend/app/tools/fix_sql_query.py"
click node_dbtool "https://github.com/shravantv/moviebot/blob/main/backend/app/db_tool.py"
click node_dbmanager "https://github.com/shravantv/moviebot/blob/main/dbmanager/db_manager.py"
click node_movielens "https://github.com/shravantv/moviebot/tree/main/ml-latest-small"

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_webapp,node_user toneBlue
class node_api,node_generate,node_execute,node_repair toneAmber
class node_dbtool,node_sqlite toneMint
class node_dbmanager,node_movielens toneRose
class node_groq,node_langsmith toneIndigo
```

## Components

### Chat interface

- [Streamlit chat](https://github.com/shravantv/moviebot/blob/main/webapp/app.py): `webapp/app.py`

### Backend orchestration

- [Query API and agent](https://github.com/shravantv/moviebot/blob/main/backend/app/main.py): `backend/app/main.py`
- [SQL generation](https://github.com/shravantv/moviebot/blob/main/backend/app/tools/generate_sql.py): `backend/app/tools/generate_sql.py`
- [SQL execution](https://github.com/shravantv/moviebot/blob/main/backend/app/tools/execute_sql_query.py): `backend/app/tools/execute_sql_query.py`
- [Query repair](https://github.com/shravantv/moviebot/blob/main/backend/app/tools/fix_sql_query.py): `backend/app/tools/fix_sql_query.py`

### SQL and data

- [Database access](https://github.com/shravantv/moviebot/blob/main/backend/app/db_tool.py): `backend/app/db_tool.py`
- **SQLite movie database**

### Database initialization

- [CSV import and schema](https://github.com/shravantv/moviebot/blob/main/dbmanager/db_manager.py): `dbmanager/db_manager.py`
- [MovieLens CSV data](https://github.com/shravantv/moviebot/tree/main/ml-latest-small): `ml-latest-small`

### Other components

- **MovieBot user**
- **Groq model service**
- **LangSmith tracing**

## Connections

- MovieBot user → Streamlit chat: asks question (evidence: `webapp/app.py`)
- Streamlit chat → Query API and agent: posts history (evidence: `webapp/app.py`)
- Query API and agent → Streamlit chat: returns answer (evidence: `backend/app/main.py`)
- Query API and agent → SQL generation: dispatches tools (evidence: `backend/app/main.py`)
- Query API and agent → SQL execution: dispatches tools (evidence: `backend/app/main.py`)
- Query API and agent → Query repair: dispatches tools (evidence: `backend/app/main.py`)
- SQL generation → Database access: reads schema (evidence: `backend/app/tools/generate_sql.py`)
- SQL execution → Database access: executes query (evidence: `backend/app/tools/execute_sql_query.py`)
- SQL generation → Groq model service: requests SQL (evidence: `backend/app/tools/generate_sql.py`)
- Query repair → Groq model service: requests correction (evidence: `backend/app/tools/fix_sql_query.py`)
- Database access → SQLite movie database: reads schema and rows (evidence: `backend/app/db_tool.py`)
- CSV import and schema → MovieLens CSV data: imports CSV files (evidence: `dbmanager/db_manager.py`)
- CSV import and schema → SQLite movie database: initializes tables (evidence: `README.md`)
- Query API and agent → LangSmith tracing: traces requests (evidence: `README.md`)
