# vineshf1/halos-ai architecture

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

- Interactive diagram: https://gitdiagram.com/vineshf1/halos-ai
- Repository: https://github.com/vineshf1/halos-ai

## Overview

Halos AI is an F1 question-answering chatbot: users ask through the web chat, the backend validates and classifies each question, then serves trivia from a hybrid RAG search or statistics through Text-to-SQL, returning a natural-language answer. Separate ingestion jobs populate the knowledge and race-statistics data stores. The README documents query rewriting, conversation context, and hybrid retrieval; sampled excerpts show the RAG retrieval and generation behavior, but not every internal step or the SQL-agent implementation.

Main entry points: [`backend/app.py`](https://github.com/vineshf1/halos-ai/blob/main/backend/app.py) (FastAPI chat API), [`backend/rag_pipeline.py`](https://github.com/vineshf1/halos-ai/blob/main/backend/rag_pipeline.py) (RAG pipeline), [`backend/db_schema.py`](https://github.com/vineshf1/halos-ai/blob/main/backend/db_schema.py) (PostgreSQL + pgvector), [`backend/rag_ingestion.py`](https://github.com/vineshf1/halos-ai/blob/main/backend/rag_ingestion.py) (Knowledge ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Chat Interface"]
  node_chat_ui["Chat interface<br/>[ChatInterface.tsx]"]
  node_chat_input["Chat input<br/>[ChatInput.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["Chat API"]
  node_backend["FastAPI chat API<br/>[app.py]"]
  node_sanitizer["Input checks<br/>[sanitizer.py]"]
  node_rate_limit["IP rate limit<br/>[rate_limiter.py]"]
  node_classifier["Query classifier<br/>[app.py]"]
end

subgraph group_answer["Answer Pipelines"]
  node_rag["RAG pipeline<br/>[rag_pipeline.py]"]
  node_sql["SQL answering<br/>[app.py]"]
end

subgraph group_data["Data Ingestion"]
  node_database[("PostgreSQL + pgvector<br/>[db_schema.py]")]
  node_rag_ingest["Knowledge ingestion<br/>[rag_ingestion.py]"]
  node_sql_ingest["Statistics ingestion<br/>[sql_ingestion.py]"]
end

node_user(("F1 questioner"))
node_nvidia["NVIDIA AI API"]
node_web_sources["Wikipedia pages"]
node_fastf1["FastF1 data"]

node_user -->|"asks"| node_chat_input
node_chat_input -->|"submits"| node_chat_ui
node_chat_ui -->|"sends message"| node_api_client
node_api_client -->|"POST chat"| node_backend
node_api_client -->|"GET health"| node_backend
node_backend -->|"checks input"| node_sanitizer
node_backend -->|"limits requests"| node_rate_limit
node_backend -->|"classifies query"| node_classifier
node_classifier -->|"routes trivia"| node_rag
node_classifier -->|"routes stats"| node_sql
node_sql -->|"falls back"| node_rag
node_rag -->|"hybrid search"| node_database
node_rag -->|"embeds and generates"| node_nvidia
node_sql -->|"generates SQL"| node_nvidia
node_sql -->|"reads statistics"| node_database
node_rag_ingest -->|"scrapes pages"| node_web_sources
node_rag_ingest -->|"embeds chunks"| node_nvidia
node_rag_ingest -->|"stores chunks"| node_database
node_sql_ingest -->|"loads race data"| node_fastf1
node_sql_ingest -->|"stores results"| node_database

click node_chat_ui "https://github.com/vineshf1/halos-ai/blob/main/frontend/src/components/ChatInterface.tsx"
click node_chat_input "https://github.com/vineshf1/halos-ai/blob/main/frontend/src/components/ChatInput.tsx"
click node_api_client "https://github.com/vineshf1/halos-ai/blob/main/frontend/src/api.ts"
click node_backend "https://github.com/vineshf1/halos-ai/blob/main/backend/app.py"
click node_sanitizer "https://github.com/vineshf1/halos-ai/blob/main/backend/sanitizer.py"
click node_rate_limit "https://github.com/vineshf1/halos-ai/blob/main/backend/rate_limiter.py"
click node_classifier "https://github.com/vineshf1/halos-ai/blob/main/backend/app.py"
click node_rag "https://github.com/vineshf1/halos-ai/blob/main/backend/rag_pipeline.py"
click node_sql "https://github.com/vineshf1/halos-ai/blob/main/backend/app.py"
click node_database "https://github.com/vineshf1/halos-ai/blob/main/backend/db_schema.py"
click node_rag_ingest "https://github.com/vineshf1/halos-ai/blob/main/backend/rag_ingestion.py"
click node_sql_ingest "https://github.com/vineshf1/halos-ai/blob/main/backend/sql_ingestion.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_ui,node_chat_input,node_api_client toneBlue
class node_backend,node_sanitizer,node_rate_limit,node_classifier toneAmber
class node_rag,node_sql,node_nvidia toneMint
class node_database,node_rag_ingest,node_sql_ingest toneRose
class node_user,node_web_sources,node_fastf1 toneIndigo
```

## Components

### Chat Interface

- [Chat interface](https://github.com/vineshf1/halos-ai/blob/main/frontend/src/components/ChatInterface.tsx): `frontend/src/components/ChatInterface.tsx`
- [Chat input](https://github.com/vineshf1/halos-ai/blob/main/frontend/src/components/ChatInput.tsx): `frontend/src/components/ChatInput.tsx`
- [API client](https://github.com/vineshf1/halos-ai/blob/main/frontend/src/api.ts): `frontend/src/api.ts`

### Chat API

- [FastAPI chat API](https://github.com/vineshf1/halos-ai/blob/main/backend/app.py): `backend/app.py`
- [Input checks](https://github.com/vineshf1/halos-ai/blob/main/backend/sanitizer.py): `backend/sanitizer.py`
- [IP rate limit](https://github.com/vineshf1/halos-ai/blob/main/backend/rate_limiter.py): `backend/rate_limiter.py`
- [Query classifier](https://github.com/vineshf1/halos-ai/blob/main/backend/app.py): `backend/app.py`

### Answer Pipelines

- [RAG pipeline](https://github.com/vineshf1/halos-ai/blob/main/backend/rag_pipeline.py): `backend/rag_pipeline.py`
- [SQL answering](https://github.com/vineshf1/halos-ai/blob/main/backend/app.py): `backend/app.py`

### Data Ingestion

- [PostgreSQL + pgvector](https://github.com/vineshf1/halos-ai/blob/main/backend/db_schema.py): `backend/db_schema.py`
- [Knowledge ingestion](https://github.com/vineshf1/halos-ai/blob/main/backend/rag_ingestion.py): `backend/rag_ingestion.py`
- [Statistics ingestion](https://github.com/vineshf1/halos-ai/blob/main/backend/sql_ingestion.py): `backend/sql_ingestion.py`

### Other components

- **F1 questioner**
- **NVIDIA AI API**
- **Wikipedia pages**
- **FastF1 data**

## Connections

- F1 questioner → Chat input: asks
- Chat input → Chat interface: submits
- Chat interface → API client: sends message
- API client → FastAPI chat API: POST chat
- API client → FastAPI chat API: GET health
- FastAPI chat API → Input checks: checks input
- FastAPI chat API → IP rate limit: limits requests
- FastAPI chat API → Query classifier: classifies query
- Query classifier → RAG pipeline: routes trivia
- Query classifier → SQL answering: routes stats
- SQL answering → RAG pipeline: falls back
- RAG pipeline → PostgreSQL + pgvector: hybrid search
- RAG pipeline → NVIDIA AI API: embeds and generates
- SQL answering → NVIDIA AI API: generates SQL
- SQL answering → PostgreSQL + pgvector: reads statistics
- Knowledge ingestion → Wikipedia pages: scrapes pages
- Knowledge ingestion → NVIDIA AI API: embeds chunks
- Knowledge ingestion → PostgreSQL + pgvector: stores chunks
- Statistics ingestion → FastF1 data: loads race data
- Statistics ingestion → PostgreSQL + pgvector: stores results