# yashusinghal69/leaguelens architecture

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

- Interactive diagram: https://gitdiagram.com/yashusinghal69/leaguelens
- Repository: https://github.com/yashusinghal69/leaguelens

## Overview

##### Project type and purpose
- This is a full-stack web application for delivering cricket statistics and AI-driven live commentary.
- The frontend is built with Next.js (TypeScript) and Tailwind CSS, serving UI components and API routes at port 3000.
- The backend is a Python FastAPI service (port 8051) that ingests cricket data, powers an AI chat/commentary pipeline, and persists/query data via CSV/SQL.

##### File structure
- Top-level:
- docker-compose.yml + Dockerfiles orchestrate two containers (frontend & backend).
- src/ holds Next.js app (pages, components, contexts).
- public/ contains static assets.
- backend/ contains FastAPI app.py and submodules under chat/, sql_with_pathway/, vector_updater.py, plus data files, logs, and scripts.
- Patterns:
- Frontend uses the Next.js “app” directory with client/server components.
- Backend is organized by feature: chat pipeline, SQL setup, vector store microservice, data-updater scripts.

##### Additional insights from README
- Two services launched via Docker Compose:
- Frontend (localhost:3000)
- Backend API (localhost:8051)
- Manual start scripts for development: start_app.sh, docker-setup.sh.
- Data update workflow: jsonfileupdate.py, vector_updater.py, and SQL setup scripts.

##### Elements
- Labels: name each container and sub-service (e.g. “Next.js Frontend”, “FastAPI Chat Service”).
- Green for backend services.
- Orange for data storage.
- Gray for external services.

##### Detail without overcomplication
- Backend feature modules as sub-components.
- Orchestration sequence for chat queries.
- Offline batch/update processes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    Browser["User's Browser"]:::frontend

    %% Frontend Container
    subgraph "Frontend Container"
        direction TB
        NextJS["Next.js Frontend"]:::frontend
        UIComponents["UI Components"]:::frontend
        ChatContext["Chat Context"]:::frontend
        CommentaryContext["Commentary Context"]:::frontend
        ChatbotPage["Chatbot Page"]:::frontend
        PlayerStats["Player Stats Pages"]:::frontend
        GlobalStyles["Global Styles"]:::frontend
        Config["Frontend Config"]:::frontend
        StartScript["Start Script"]:::frontend
    end

    %% Backend Container
    subgraph "Backend Container"
        direction TB
        FastAPI["FastAPI Backend"]:::backend
        MainAPI["Chat API Router"]:::backend
        ChatApp["Chat Pipeline Orchestration"]:::backend
        LiveProcessor["Live Match Processor"]:::backend
        VectorStore["Vector Store Service"]:::backend
        WebSearch["Web Search Integration"]:::backend
        SQLAgent["SQL Agent for Chat"]:::backend
        SQLSetup["SQL Setup Script"]:::backend
        DeliveriesCSV["Deliveries CSV"]:::storage
        CommentaryJSON["Commentary History Store"]:::storage
        RawData["Raw Data Files"]:::storage
        Logs["Logging Directory"]:::storage
        RunCommentary["Batch Commentary Runner"]:::backend
        JSONUpdate["JSON Update Script"]:::backend
        VectorUpdater["Vector Updater Script"]:::backend
        VectorHelpers["Vector Updater Data & Helpers"]:::backend
        SQLWithPathway["SQL with Pathway Module"]:::backend
        CoreServices["Core Backend Services"]:::backend
        Requirements["Backend Requirements"]:::backend
    end

    %% External Services
    OpenAI["OpenAI API"]:::external
    WebSearchAPI["Web Search API"]:::external

    %% Connections
    Browser --> NextJS
    NextJS --> MainAPI
    MainAPI --> ChatApp
    ChatApp --> VectorStore
    ChatApp --> OpenAI
    ChatApp --> SQLAgent
    ChatApp --> LiveProcessor
    ChatApp --> CommentaryJSON
    ChatApp --> DeliveriesCSV
    SQLAgent --> SQLSetup
    SQLWithPathway --> SQLSetup
    VectorUpdater --> VectorStore
    JSONUpdate --> CommentaryJSON
    VectorHelpers --> VectorUpdater
    RunCommentary --> CommentaryJSON
    RunCommentary --> DeliveriesCSV

    %% Click Events Frontend
    click NextJS "https://github.com/yashusinghal69/leaguelens/tree/main/src/"
    click UIComponents "https://github.com/yashusinghal69/leaguelens/tree/main/src/app/_components/"
    click ChatContext "https://github.com/yashusinghal69/leaguelens/blob/main/src/app/_context/Chat.tsx"
    click CommentaryContext "https://github.com/yashusinghal69/leaguelens/blob/main/src/app/_context/CommentaryContext.tsx"
    click ChatbotPage "https://github.com/yashusinghal69/leaguelens/blob/main/src/app/chatbot/page.tsx"
    click PlayerStats "https://github.com/yashusinghal69/leaguelens/tree/main/src/app/playerstats/"
    click GlobalStyles "https://github.com/yashusinghal69/leaguelens/blob/main/src/app/globals.css"
    click GlobalStyles "https://github.com/yashusinghal69/leaguelens/blob/main/tailwind.config.js"
    click Config "https://github.com/yashusinghal69/leaguelens/blob/main/next.config.ts"
    click Config "https://github.com/yashusinghal69/leaguelens/blob/main/tsconfig.json"
    click Config "https://github.com/yashusinghal69/leaguelens/blob/main/postcss.config.mjs"
    click StartScript "https://github.com/yashusinghal69/leaguelens/blob/main/start_app.sh"

    %% Click Events Docker
    click docker_compose "https://github.com/yashusinghal69/leaguelens/blob/main/docker-compose.yml"
    click Dockerfile "https://github.com/yashusinghal69/leaguelens/tree/main/Dockerfile"
    click BackendDockerfile "https://github.com/yashusinghal69/leaguelens/tree/main/backend/Dockerfile"
    click EnvExample "https://github.com/yashusinghal69/leaguelens/blob/main/ .env.example"
    click BackendEnv "https://github.com/yashusinghal69/leaguelens/blob/main/backend/.env.example"
    click DockerIgnore "https://github.com/yashusinghal69/leaguelens/blob/main/.dockerignore"
    click BackendDockerIgnore "https://github.com/yashusinghal69/leaguelens/blob/main/backend/.dockerignore"

    %% Click Events Backend
    click FastAPI "https://github.com/yashusinghal69/leaguelens/blob/main/backend/app.py"
    click MainAPI "https://github.com/yashusinghal69/leaguelens/blob/main/backend/chat/main_api.py"
    click ChatApp "https://github.com/yashusinghal69/leaguelens/blob/main/backend/chat/chat_app.py"
    click LiveProcessor "https://github.com/yashusinghal69/leaguelens/blob/main/backend/chat/live_match_processor.py"
    click VectorStore "https://github.com/yashusinghal69/leaguelens/blob/main/backend/chat/vector_store_server.py"
    click WebSearch "https://github.com/yashusinghal69/leaguelens/blob/main/backend/chat/websearch.py"
    click SQLAgent "https://github.com/yashusinghal69/leaguelens/blob/main/backend/chat/langgraph_agent_sql.py"
    click SQLSetup "https://github.com/yashusinghal69/leaguelens/blob/main/backend/chat/sql_setup.py"
    click DeliveriesCSV "https://github.com/yashusinghal69/leaguelens/blob/main/backend/chat/deliveries.csv"
    click CommentaryJSON "https://github.com/yashusinghal69/leaguelens/blob/main/backend/commentary_history.json"
    click RawData "https://github.com/yashusinghal69/leaguelens/blob/main/backend/data.json"
    click RawData "https://github.com/yashusinghal69/leaguelens/blob/main/backend/data_live.json"
    click RawData "https://github.com/yashusinghal69/leaguelens/blob/main/backend/deliveries.csv"
    click RawData "https://github.com/yashusinghal69/leaguelens/blob/main/backend/ipl_player_statistics_updated.csv"
    click Logs "https://github.com/yashusinghal69/leaguelens/tree/main/backend/logs/"
    click RunCommentary "https://github.com/yashusinghal69/leaguelens/blob/main/backend/run_commentary.py"
    click JSONUpdate "https://github.com/yashusinghal69/leaguelens/blob/main/backend/jsonfileupdate.py"
    click VectorUpdater "https://github.com/yashusinghal69/leaguelens/blob/main/backend/vector_updater.py"
    click VectorHelpers "https://github.com/yashusinghal69/leaguelens/tree/main/backend/vector_updater.py/data/"
    click VectorHelpers "https://github.com/yashusinghal69/leaguelens/blob/main/backend/cricket_qa.csv"
    click VectorHelpers "https://github.com/yashusinghal69/leaguelens/blob/main/backend/cricket_vector_loader.py"
    click VectorHelpers "https://github.com/yashusinghal69/leaguelens/blob/main/backend/cricket_qa_generator.py"
    click SQLWithPathway "https://github.com/yashusinghal69/leaguelens/tree/main/backend/sql_with_pathway/"
    click CoreServices "https://github.com/yashusinghal69/leaguelens/blob/main/backend/src/main.py"
    click CoreServices "https://github.com/yashusinghal69/leaguelens/blob/main/backend/src/commentary_generator.py"
    click CoreServices "https://github.com/yashusinghal69/leaguelens/blob/main/backend/src/data_processor.py"
    click Requirements "https://github.com/yashusinghal69/leaguelens/blob/main/backend/requirements.txt"
    click Requirements "https://github.com/yashusinghal69/leaguelens/blob/main/requirements.txt"
    click docker_setup "https://github.com/yashusinghal69/leaguelens/blob/main/docker-setup.sh"

    %% Styles
    classDef frontend fill:#blue,color:#fff,stroke:#333,stroke-width:1px;
    classDef backend fill:#9f6,stroke:#333,stroke-width:1px;
    classDef storage fill:#f90,stroke:#333,stroke-width:1px;
    classDef external fill:#ccc,stroke:#333,stroke-width:1px;
```
