# sandeepkr24/gridmind architecture

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

- Interactive diagram: https://gitdiagram.com/sandeepkr24/gridmind
- Repository: https://github.com/sandeepkr24/gridmind

## Overview

GridMind is an AI Formula 1 analyst whose main workflow turns a user question into resolved race/session entities, fetches missing timing data, runs validated read-only SQL, and returns an answer with evidence. Separate product branches provide race dashboards, championship standings, and generated reports. The README documents these capabilities and API behavior; source excerpts confirm key agent, ingestion, database, and standings relationships. Several route and UI internals were not sampled, so those connections are shown only where the README supports them.

Main entry points: [`backend/app/api/routes`](https://github.com/sandeepkr24/gridmind/tree/main/backend/app/api/routes) (HTTP routes), [`frontend/lib/api/client.ts`](https://github.com/sandeepkr24/gridmind/blob/main/frontend/lib/api/client.ts) (API client), [`backend/app/agent/orchestrator.py`](https://github.com/sandeepkr24/gridmind/blob/main/backend/app/agent/orchestrator.py) (Chat orchestrator), [`backend/app/db/database.py`](https://github.com/sandeepkr24/gridmind/blob/main/backend/app/db/database.py) (Postgres)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web experience"]
  node_web_chat["Chat page<br/>[page.tsx]"]
  node_web_races["Race pages<br/>[page.tsx]"]
  node_web_home["Dashboard<br/>[page.tsx]"]
  node_web_reports["Report page<br/>[page.tsx]"]
  node_web_loading["Ingestion progress<br/>[LoadingPit.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_api["API surface"]
  node_api_routes["HTTP routes"]
  node_app["Application wiring<br/>[main.py]"]
end

subgraph group_analysis["Chat analysis"]
  node_chat_agent["Chat orchestrator<br/>[orchestrator.py]"]
  node_resolver["Entity resolution<br/>[entity_resolver.py]"]
  node_ingestion_gate["Ingestion gate<br/>[ingestion_gate.py]"]
  node_sql_agent["SQL answering<br/>[sql_agent.py]"]
  node_llm["LLM provider"]
end

subgraph group_data["Race data"]
  node_job_runner["Session job runner<br/>[runner.py]"]
  node_fastf1["FastF1 provider<br/>[fastf1_provider.py]"]
  node_normalizer["Timing normalizer<br/>[normalizer.py]"]
  node_analytics["Race statistics<br/>[race_stats.py]"]
  node_database[("Postgres<br/>[database.py]")]
end

subgraph group_reporting["Standings and reports"]
  node_standings_service["Standings cache"]
  node_jolpica["Jolpica standings"]
  node_reports["Report generation"]
  node_report_jobs["Report jobs<br/>[jobs.py]"]
end

node_user(("F1 fan"))

node_user -->|"asks question"| node_web_chat
node_user -->|"views race"| node_web_races
node_user -->|"views season"| node_web_home
node_user -->|"reads report"| node_web_reports
node_web_chat -.->|"requests data"| node_api_client
node_web_races -.->|"requests data"| node_api_client
node_web_home -.->|"requests data"| node_api_client
node_web_reports -.->|"requests report"| node_api_client
node_api_client -->|"calls API"| node_api_routes
node_api_routes -->|"registered by"| node_app
node_api_routes -->|"dispatches chat"| node_chat_agent
node_chat_agent -->|"resolves entities"| node_resolver
node_chat_agent -->|"checks data"| node_ingestion_gate
node_chat_agent -->|"queries sessions"| node_sql_agent
node_chat_agent -->|"generates answer"| node_llm
node_resolver -->|"extracts mentions"| node_llm
node_ingestion_gate -->|"submits fetch"| node_job_runner
node_job_runner -->|"fetches session"| node_fastf1
node_job_runner -->|"normalizes data"| node_normalizer
node_normalizer -.->|"stores timing"| node_database
node_sql_agent -->|"runs read-only SQL"| node_database
node_api_routes -->|"starts ingestion"| node_job_runner
node_web_loading -.->|"polls job"| node_api_client
node_api_routes -->|"serves race stats"| node_analytics
node_analytics -.->|"reads timing"| node_database
node_api_routes -->|"serves standings"| node_standings_service
node_standings_service -->|"refreshes standings"| node_jolpica
node_standings_service -->|"caches standings"| node_database
node_api_routes -->|"starts report job"| node_report_jobs
node_report_jobs -->|"builds report"| node_reports
node_reports -->|"writes prose"| node_llm
node_reports -.->|"stores report"| node_database

click node_web_chat "https://github.com/sandeepkr24/gridmind/blob/main/frontend/app/chat/page.tsx"
click node_web_races "https://github.com/sandeepkr24/gridmind/blob/main/frontend/app/races/%5Bid%5D/page.tsx"
click node_web_home "https://github.com/sandeepkr24/gridmind/blob/main/frontend/app/page.tsx"
click node_web_reports "https://github.com/sandeepkr24/gridmind/blob/main/frontend/app/reports/%5Bid%5D/page.tsx"
click node_web_loading "https://github.com/sandeepkr24/gridmind/blob/main/frontend/components/LoadingPit.tsx"
click node_api_client "https://github.com/sandeepkr24/gridmind/blob/main/frontend/lib/api/client.ts"
click node_api_routes "https://github.com/sandeepkr24/gridmind/tree/main/backend/app/api/routes"
click node_app "https://github.com/sandeepkr24/gridmind/blob/main/backend/app/main.py"
click node_chat_agent "https://github.com/sandeepkr24/gridmind/blob/main/backend/app/agent/orchestrator.py"
click node_resolver "https://github.com/sandeepkr24/gridmind/blob/main/backend/app/agent/entity_resolver.py"
click node_ingestion_gate "https://github.com/sandeepkr24/gridmind/blob/main/backend/app/agent/ingestion_gate.py"
click node_sql_agent "https://github.com/sandeepkr24/gridmind/blob/main/backend/app/agent/sql_agent.py"
click node_llm "https://github.com/sandeepkr24/gridmind/tree/main/backend/app/llm"
click node_job_runner "https://github.com/sandeepkr24/gridmind/blob/main/backend/app/ingestion/runner.py"
click node_fastf1 "https://github.com/sandeepkr24/gridmind/blob/main/backend/app/ingestion/fastf1_provider.py"
click node_normalizer "https://github.com/sandeepkr24/gridmind/blob/main/backend/app/ingestion/normalizer.py"
click node_analytics "https://github.com/sandeepkr24/gridmind/blob/main/backend/app/analytics/race_stats.py"
click node_database "https://github.com/sandeepkr24/gridmind/blob/main/backend/app/db/database.py"
click node_standings_service "https://github.com/sandeepkr24/gridmind/blob/main/backend/app/ingestion/standings_service.py"
click node_jolpica "https://github.com/sandeepkr24/gridmind/blob/main/backend/app/ingestion/standings_provider.py"
click node_reports "https://github.com/sandeepkr24/gridmind/tree/main/backend/app/reports"
click node_report_jobs "https://github.com/sandeepkr24/gridmind/blob/main/backend/app/reports/jobs.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_web_chat,node_web_races,node_web_home,node_web_reports,node_web_loading,node_api_client toneBlue
class node_api_routes,node_app toneAmber
class node_chat_agent,node_resolver,node_ingestion_gate,node_sql_agent,node_llm toneMint
class node_job_runner,node_fastf1,node_normalizer,node_analytics,node_database toneRose
class node_standings_service,node_jolpica,node_reports,node_report_jobs,node_user toneIndigo
```

## Components

### Web experience

- [Chat page](https://github.com/sandeepkr24/gridmind/blob/main/frontend/app/chat/page.tsx): `frontend/app/chat/page.tsx`
- [Race pages](https://github.com/sandeepkr24/gridmind/blob/main/frontend/app/races/%5Bid%5D/page.tsx): `frontend/app/races/[id]/page.tsx`
- [Dashboard](https://github.com/sandeepkr24/gridmind/blob/main/frontend/app/page.tsx): `frontend/app/page.tsx`
- [Report page](https://github.com/sandeepkr24/gridmind/blob/main/frontend/app/reports/%5Bid%5D/page.tsx): `frontend/app/reports/[id]/page.tsx`
- [Ingestion progress](https://github.com/sandeepkr24/gridmind/blob/main/frontend/components/LoadingPit.tsx): `frontend/components/LoadingPit.tsx`
- [API client](https://github.com/sandeepkr24/gridmind/blob/main/frontend/lib/api/client.ts): `frontend/lib/api/client.ts`

### API surface

- [HTTP routes](https://github.com/sandeepkr24/gridmind/tree/main/backend/app/api/routes): `backend/app/api/routes`
- [Application wiring](https://github.com/sandeepkr24/gridmind/blob/main/backend/app/main.py): `backend/app/main.py`

### Chat analysis

- [Chat orchestrator](https://github.com/sandeepkr24/gridmind/blob/main/backend/app/agent/orchestrator.py): `backend/app/agent/orchestrator.py`
- [Entity resolution](https://github.com/sandeepkr24/gridmind/blob/main/backend/app/agent/entity_resolver.py): `backend/app/agent/entity_resolver.py`
- [Ingestion gate](https://github.com/sandeepkr24/gridmind/blob/main/backend/app/agent/ingestion_gate.py): `backend/app/agent/ingestion_gate.py`
- [SQL answering](https://github.com/sandeepkr24/gridmind/blob/main/backend/app/agent/sql_agent.py): `backend/app/agent/sql_agent.py`
- [LLM provider](https://github.com/sandeepkr24/gridmind/tree/main/backend/app/llm): `backend/app/llm`

### Race data

- [Session job runner](https://github.com/sandeepkr24/gridmind/blob/main/backend/app/ingestion/runner.py): `backend/app/ingestion/runner.py`
- [FastF1 provider](https://github.com/sandeepkr24/gridmind/blob/main/backend/app/ingestion/fastf1_provider.py): `backend/app/ingestion/fastf1_provider.py`
- [Timing normalizer](https://github.com/sandeepkr24/gridmind/blob/main/backend/app/ingestion/normalizer.py): `backend/app/ingestion/normalizer.py`
- [Race statistics](https://github.com/sandeepkr24/gridmind/blob/main/backend/app/analytics/race_stats.py): `backend/app/analytics/race_stats.py`
- [Postgres](https://github.com/sandeepkr24/gridmind/blob/main/backend/app/db/database.py): `backend/app/db/database.py`

### Standings and reports

- [Standings cache](https://github.com/sandeepkr24/gridmind/blob/main/backend/app/ingestion/standings_service.py): `backend/app/ingestion/standings_service.py`
- [Jolpica standings](https://github.com/sandeepkr24/gridmind/blob/main/backend/app/ingestion/standings_provider.py): `backend/app/ingestion/standings_provider.py`
- [Report generation](https://github.com/sandeepkr24/gridmind/tree/main/backend/app/reports): `backend/app/reports`
- [Report jobs](https://github.com/sandeepkr24/gridmind/blob/main/backend/app/reports/jobs.py): `backend/app/reports/jobs.py`

### Other components

- **F1 fan**

## Connections

- F1 fan → Chat page: asks question (evidence: `README.md`)
- F1 fan → Race pages: views race (evidence: `README.md`)
- F1 fan → Dashboard: views season (evidence: `README.md`)
- F1 fan → Report page: reads report (evidence: `README.md`)
- Chat page → API client: requests data
- Race pages → API client: requests data
- Dashboard → API client: requests data
- Report page → API client: requests report
- API client → HTTP routes: calls API (evidence: `README.md`)
- HTTP routes → Application wiring: registered by (evidence: `backend/app/main.py`)
- HTTP routes → Chat orchestrator: dispatches chat (evidence: `README.md`)
- Chat orchestrator → Entity resolution: resolves entities (evidence: `backend/app/agent/orchestrator.py`)
- Chat orchestrator → Ingestion gate: checks data (evidence: `backend/app/agent/orchestrator.py`)
- Chat orchestrator → SQL answering: queries sessions (evidence: `backend/app/agent/orchestrator.py`)
- Chat orchestrator → LLM provider: generates answer (evidence: `backend/app/agent/orchestrator.py`)
- Entity resolution → LLM provider: extracts mentions (evidence: `backend/app/agent/entity_resolver.py`)
- Ingestion gate → Session job runner: submits fetch (evidence: `backend/app/agent/ingestion_gate.py`)
- Session job runner → FastF1 provider: fetches session (evidence: `backend/app/ingestion/runner.py`)
- Session job runner → Timing normalizer: normalizes data (evidence: `backend/app/ingestion/runner.py`)
- Timing normalizer → Postgres: stores timing
- SQL answering → Postgres: runs read-only SQL (evidence: `README.md`)
- HTTP routes → Session job runner: starts ingestion (evidence: `README.md`)
- Ingestion progress → API client: polls job
- HTTP routes → Race statistics: serves race stats (evidence: `README.md`)
- Race statistics → Postgres: reads timing
- HTTP routes → Standings cache: serves standings (evidence: `README.md`)
- Standings cache → Jolpica standings: refreshes standings (evidence: `backend/app/ingestion/standings_service.py`)
- Standings cache → Postgres: caches standings (evidence: `backend/app/ingestion/standings_service.py`)
- HTTP routes → Report jobs: starts report job (evidence: `README.md`)
- Report jobs → Report generation: builds report (evidence: `backend/app/reports/jobs.py`)
- Report generation → LLM provider: writes prose (evidence: `README.md`)
- Report generation → Postgres: stores report
