# sanjogbhalla16/velocityai architecture

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

- Interactive diagram: https://gitdiagram.com/sanjogbhalla16/velocityai
- Repository: https://github.com/sanjogbhalla16/velocityai

## Overview

##### Project Type & Purpose
- VelocityAI is a full-stack, real-time F1 data and AI chatbot application.
- It integrates data scraping, vector search (with DataStax AstraDB), and retrieval-augmented generation powered by OpenAI and LangChain.
- The application has a dedicated backend built with FastAPI and a frontend developed using Next.js.

##### Major Components
a. Frontend:
- Built with Next.js (folder: frontend). It includes standard page components (such as chat interface pages, layout, and UI components).
- It makes API calls to the backend and provides the user interface.

b. Backend:
- Built with FastAPI (evidenced by the use of API endpoints, e.g., in Backend/api/index.py, and main.py for the server entry).
- Contains sub-modules for specific functions:
i. API Handlers: Responsible for managing chat endpoints, querying F1 data (Backend/api/query_f1_data.py), and maintaining chat histories (chat_history.db in the API folder).
ii. Data Scraping: The “scraper” directory shows that a dedicated script (scraper.py) extracts F1 data and stores it (scraped_f1_data.json).
iii. Data Population & Processing: The “populate_db” module handles creating collections, loading data, splitting F1 data, and updating the chat database.

c. Databases & External Services:
- Internal database: A local SQLite file (chat_history.db) for storing chat histories.
- External vector database: DataStax AstraDB (mentioned in the README) used for storing custom embeddings and supporting efficient vector search.
- Third-Party Services: OpenAI for powering AI responses, and LangChain for chain-of-thought or retrieval-augmented generation.
- Web scraping tools (likely using Pyppeteer) for gathering dynamic F1 data.

##### Architectural Relationships & Interactions
- The Frontend and Backend are separated clearly:
- The Frontend (Next.js) communicates with the Backend via API endpoints.
- The Backend acts as the central hub:
- It serves API endpoints that process user requests, query F1 data, and generate responses using ChatGPT-like models.
- It also integrates the data ingestion pipeline: the scraper gathers real-time or historical data; then the populate_db scripts process and update the SQL or vector database.
- External dependencies:
- The backend reaches out to OpenAI and LangChain for generating responses.
- It also interacts with DataStax AstraDB to retrieve relevant F1 knowledge using vector search.
- Request/response flow from Frontend to Backend.
- Data update/insertion flows from scraper/population modules to databases.
- Integration calls from Backend to external AI & vector database services.

- Data requests from Frontend → Backend API.
- Processing calls from Backend → Chat history DB and External Services.
- Data flows from Scraper and Populate modules → Databases.
- Rectangles for application modules (Frontend, Backend).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend Layer"
        FE["Frontend (Next.js UI)"]:::frontend
    end

    subgraph "Backend Layer"
        API["API (FastAPI endpoints)"]:::backend
        HANDLERS["API Handlers (Query F1 & Chat)"]:::backend
        SCRAPER["Data Scraper Module"]:::backend
        POPULATE["Data Population Module"]:::backend
    end

    subgraph "Databases"
        CHATDB["Local Chat History DB (SQLite)"]:::database
        VECTORDB["External Vector DB (DataStax AstraDB)"]:::database
    end

    subgraph "External Services"
        EXTSVC["OpenAI & LangChain Integration"]:::external
    end

    FE -->|"request/response"| API
    API -->|"calls"| HANDLERS
    API -->|"invokes"| EXTSVC
    API -->|"retrieves"| VECTORDB
    HANDLERS -->|"queries"| CHATDB
    SCRAPER -.->|"sends data"| POPULATE
    POPULATE -->|"updates"| VECTORDB
    POPULATE -->|"updates"| CHATDB

    %% Click Events
    click FE "https://github.com/sanjogbhalla16/velocityai/tree/main/frontend/"
    click API "https://github.com/sanjogbhalla16/velocityai/blob/main/Backend/main.py"
    click API "https://github.com/sanjogbhalla16/velocityai/blob/main/Backend/api/index.py"
    click HANDLERS "https://github.com/sanjogbhalla16/velocityai/blob/main/Backend/api/query_f1_data.py"
    click HANDLERS "https://github.com/sanjogbhalla16/velocityai/blob/main/Backend/api/chat_history.db"
    click SCRAPER "https://github.com/sanjogbhalla16/velocityai/blob/main/Backend/scraper/scraper.py"
    click SCRAPER "https://github.com/sanjogbhalla16/velocityai/blob/main/Backend/scraper/scraped_f1_data.json"
    click POPULATE "https://github.com/sanjogbhalla16/velocityai/tree/main/Backend/populate_db/"

    %% Styles
    classDef frontend fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef backend fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef database fill:#FFE0B2,stroke:#EF6C00,stroke-width:2px,stroke-dasharray: 5,5;
    classDef external fill:#FFCDD2,stroke:#C62828,stroke-width:2px,stroke-dasharray: 5,5;
```
