# sjain022/calhacks architecture

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

- Interactive diagram: https://gitdiagram.com/sjain022/calhacks
- Repository: https://github.com/sjain022/calhacks

## Overview

1. **High-level shape**
   - This repo is split into three runtime tiers: a **React frontend**, a **Python/Flask backend**, and a **Node.js search service** backed by **Chroma DB**.
   - The product goal is a **chess AI tutor**: users upload or fetch Lichess games, analyze them, get feedback, and search a database of games/patterns with semantic retrieval.

2. **Frontend application**
   - The `frontend/` package is a **Vite + React** app styled with **Tailwind/PostCSS**.
   - The UI is organized around route-level screens in `src/app/`: `Login`, `Choose`, `UploadSearch`, `Search`, `Train`, and `Analyze`.
   - `Navbar` is the shared navigation shell, and the chess-specific UI lives in `components/ChessGame.jsx` and `ChessGameChat.jsx`, indicating an interactive board plus AI/chat-style feedback experience.

3. **Frontend responsibility**
   - The frontend is the orchestration layer for the user experience: login, selecting a workflow, uploading/searching games, training, and reviewing analysis.
   - It likely calls multiple backend endpoints depending on the workflow, rather than doing chess analysis locally in the browser.

4. **Python backend**
   - The `backend/` folder contains a small **Flask** service (`app.py`, `methods.py`) that appears to own the core application logic for game evaluation and AI-assisted tutoring.
   - The presence of `vercel.json` suggests this backend is intended to be deployed separately, potentially as a serverless Flask app.
   - This layer is the main API boundary for analysis/tutoring functionality and likely mediates calls to external chess/LLM services.

5. **Search and retrieval service**
   - `search-engine-nodejs-server/` is a separate **Node.js** service (`server.js`) dedicated to semantic search over chess games.
   - It uses **Chroma DB** for vector storage and retrieval, with persistent local data under `getting-started/` and `chroma.sqlite3`.
   - The `docker-compose.yml` and Chroma files indicate this subsystem is treated as an independent retrieval backend rather than embedded in the Flask app.

6. **Semantic search data store**
   - The Chroma data directory contains vector index artifacts (`data_level0.bin`, `header.bin`, `length.bin`, `link_lists.bin`), which means the system indexes chess-game text/metadata for similarity search.
   - This is the infrastructure behind queries like finding games by players, openings, or themes, such as the example in the README.

7. **Primary data flows**
   - **User flow 1: game analysis** → frontend submits a Lichess game or user input → Flask backend evaluates moves and generates feedback/puzzles → frontend renders analysis and chess UI.
   - **User flow 2: semantic search** → frontend sends a search query → Node/Chroma service retrieves similar games or relevant records → results are shown in the search/upload views.
   - **User flow 3: training/puzzle generation** → backend uses analysis output plus AI services to produce customized training material.

8. **External AI/chess services**
   - The README explicitly lists integrations with **Google Gemini**, **Rapid Chess API**, **Llama API**, and **Groq API**.
   - These are important architecture boundaries: the backend is not just a local rules engine; it is an **AI-orchestrated service** that likely combines chess evaluation with LLM-generated explanations and puzzle creation.

9. **Chess domain focus**
   - The app is centered on **Lichess game evaluation** and **customized puzzles** derived from a user’s own games.
   - That means the core domain objects are likely games, positions, move sequences, evaluation results, and personalized recommendations rather than generic chat or generic search.

10. **Separation of concerns**
   - The repo cleanly separates:
     - **presentation** in `frontend/`
     - **analysis/tutoring logic** in `backend/`
     - **retrieval/indexing** in `search-engine-nodejs-server/`
   - This separation matters for an architecture diagram because the search subsystem is independent from the tutoring backend, even though both serve chess-related features.

11. **Local development/runtime topology**
   - To run the full system locally, all three services need to be started independently: frontend dev server, Flask backend, and Node search server.
   - Chroma runs as its own local database service/process and persists indexed vectors on disk.

12. **What to show in a diagram**
   - Draw the frontend as the single user-facing entry point.
   - Show two backend paths from the frontend: one to the **Flask AI/tutoring API**, one to the **Node/Chroma semantic search API**.
   - Show the Flask service connecting outward to external chess/LLM APIs.
   - Show the Node search service connected to Chroma persistence.

Main entry points: [`frontend/src/main.jsx`](https://github.com/sjain022/calhacks/blob/main/frontend/src/main.jsx) (React app), [`frontend/src/app/Analyze.jsx`](https://github.com/sjain022/calhacks/blob/main/frontend/src/app/Analyze.jsx) (Analyze), [`search-engine-nodejs-server/server.js`](https://github.com/sjain022/calhacks/blob/main/search-engine-nodejs-server/server.js) (Search API), [`backend/app.py`](https://github.com/sjain022/calhacks/blob/main/backend/app.py) (Flask API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["React app<br/>vite-react<br/>[main.jsx]"]
  node_frontend_nav["Navbar<br/>ui shell<br/>[Navbar.jsx]"]
  node_frontend_login["Login<br/>screen<br/>[Login.jsx]"]
  node_frontend_choose["Choose<br/>screen<br/>[Choose.jsx]"]
  node_frontend_upload["Upload/Search<br/>screen<br/>[UploadSearch.jsx]"]
  node_frontend_search["Search<br/>screen<br/>[Search.jsx]"]
  node_frontend_train["Train<br/>screen<br/>[Train.jsx]"]
  node_frontend_analyze["Analyze<br/>screen<br/>[Analyze.jsx]"]
  node_frontend_board["Chess board<br/>chess ui<br/>[ChessGame.jsx]"]
  node_frontend_chat["Coach chat<br/>chat ui<br/>[ChessGameChat.jsx]"]
end

subgraph group_backend["Python API"]
  node_backend_app["Flask API<br/>python service<br/>[app.py]"]
  node_backend_methods["Analysis core<br/>domain logic<br/>[methods.py]"]
end

subgraph group_search["Search Service"]
  node_search_server["Search API<br/>node service<br/>[server.js]"]
end

subgraph group_data["Vector Store"]
  node_chroma_db[("Chroma store<br/>vector db<br/>[chroma.sqlite3]")]
  node_chroma_index["Index files<br/>vector artifacts<br/>[data_level0.bin]"]
end

subgraph group_external["External APIs"]
  node_external_ai{{"AI services<br/>llm/chess apis"}}
end

node_frontend_app -->|"renders"| node_frontend_nav
node_frontend_app -->|"routes to"| node_frontend_login
node_frontend_app -->|"routes to"| node_frontend_choose
node_frontend_app -->|"routes to"| node_frontend_upload
node_frontend_app -->|"routes to"| node_frontend_search
node_frontend_app -->|"routes to"| node_frontend_train
node_frontend_app -->|"routes to"| node_frontend_analyze
node_frontend_analyze -->|"uses"| node_frontend_board
node_frontend_analyze -->|"uses"| node_frontend_chat
node_frontend_upload -->|"analyzes games"| node_backend_app
node_frontend_analyze -->|"requests feedback"| node_backend_app
node_frontend_train -->|"generates puzzles"| node_backend_app
node_backend_app -->|"delegates"| node_backend_methods
node_backend_methods -->|"calls"| node_external_ai
node_frontend_search -->|"queries"| node_search_server
node_frontend_upload -->|"searches"| node_search_server
node_search_server -->|"reads/writes"| node_chroma_db
node_search_server -->|"uses"| node_chroma_index

click node_frontend_app "https://github.com/sjain022/calhacks/blob/main/frontend/src/main.jsx"
click node_frontend_nav "https://github.com/sjain022/calhacks/blob/main/frontend/src/app/Navbar.jsx"
click node_frontend_login "https://github.com/sjain022/calhacks/blob/main/frontend/src/app/Login.jsx"
click node_frontend_choose "https://github.com/sjain022/calhacks/blob/main/frontend/src/app/Choose.jsx"
click node_frontend_upload "https://github.com/sjain022/calhacks/blob/main/frontend/src/app/UploadSearch.jsx"
click node_frontend_search "https://github.com/sjain022/calhacks/blob/main/frontend/src/app/Search.jsx"
click node_frontend_train "https://github.com/sjain022/calhacks/blob/main/frontend/src/app/Train.jsx"
click node_frontend_analyze "https://github.com/sjain022/calhacks/blob/main/frontend/src/app/Analyze.jsx"
click node_frontend_board "https://github.com/sjain022/calhacks/blob/main/frontend/src/app/components/ChessGame.jsx"
click node_frontend_chat "https://github.com/sjain022/calhacks/blob/main/frontend/src/app/components/ChessGameChat.jsx"
click node_backend_app "https://github.com/sjain022/calhacks/blob/main/backend/app.py"
click node_backend_methods "https://github.com/sjain022/calhacks/blob/main/backend/methods.py"
click node_search_server "https://github.com/sjain022/calhacks/blob/main/search-engine-nodejs-server/server.js"
click node_chroma_db "https://github.com/sjain022/calhacks/blob/main/search-engine-nodejs-server/getting-started/chroma.sqlite3"
click node_chroma_index "https://github.com/sjain022/calhacks/blob/main/search-engine-nodejs-server/getting-started/69b53940-864f-45e4-bd43-0b8dbe0841cd/data_level0.bin"

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_frontend_app,node_frontend_nav,node_frontend_login,node_frontend_choose,node_frontend_upload,node_frontend_search,node_frontend_train,node_frontend_analyze,node_frontend_board,node_frontend_chat toneBlue
class node_backend_app,node_backend_methods toneAmber
class node_search_server toneMint
class node_chroma_db,node_chroma_index toneRose
class node_external_ai toneIndigo
```

## Components

### Frontend

React Vite UI and route-level screens

- [React app](https://github.com/sjain022/calhacks/blob/main/frontend/src/main.jsx): vite-react · User-facing chess tutor interface and workflow orchestration · `frontend/src/main.jsx`
- [Navbar](https://github.com/sjain022/calhacks/blob/main/frontend/src/app/Navbar.jsx): ui shell · Shared navigation and top-level screen framing · `frontend/src/app/Navbar.jsx`
- [Login](https://github.com/sjain022/calhacks/blob/main/frontend/src/app/Login.jsx): screen · Authentication entry screen · `frontend/src/app/Login.jsx`
- [Choose](https://github.com/sjain022/calhacks/blob/main/frontend/src/app/Choose.jsx): screen · Workflow selection screen · `frontend/src/app/Choose.jsx`
- [Upload/Search](https://github.com/sjain022/calhacks/blob/main/frontend/src/app/UploadSearch.jsx): screen · Game upload and search entry screen · `frontend/src/app/UploadSearch.jsx`
- [Search](https://github.com/sjain022/calhacks/blob/main/frontend/src/app/Search.jsx): screen · Semantic search results screen · `frontend/src/app/Search.jsx`
- [Train](https://github.com/sjain022/calhacks/blob/main/frontend/src/app/Train.jsx): screen · Training and puzzle workflow screen · `frontend/src/app/Train.jsx`
- [Analyze](https://github.com/sjain022/calhacks/blob/main/frontend/src/app/Analyze.jsx): screen · Game analysis and feedback screen · `frontend/src/app/Analyze.jsx`
- [Chess board](https://github.com/sjain022/calhacks/blob/main/frontend/src/app/components/ChessGame.jsx): chess ui · Interactive board and move visualization · `frontend/src/app/components/ChessGame.jsx`
- [Coach chat](https://github.com/sjain022/calhacks/blob/main/frontend/src/app/components/ChessGameChat.jsx): chat ui · Conversational feedback and tutoring panel · `frontend/src/app/components/ChessGameChat.jsx`

### Python API

Flask tutoring and analysis service

- [Flask API](https://github.com/sjain022/calhacks/blob/main/backend/app.py): python service · Main analysis and tutoring API boundary · `backend/app.py`
- [Analysis core](https://github.com/sjain022/calhacks/blob/main/backend/methods.py): domain logic · Game evaluation, tutoring, and puzzle generation logic · `backend/methods.py`

### Search Service

Node.js semantic retrieval layer

- [Search API](https://github.com/sjain022/calhacks/blob/main/search-engine-nodejs-server/server.js): node service · Semantic search service for chess games and patterns · `search-engine-nodejs-server/server.js`

### Vector Store

Chroma persistence and indexed artifacts

- [Chroma store](https://github.com/sjain022/calhacks/blob/main/search-engine-nodejs-server/getting-started/chroma.sqlite3): vector db · Persistent vector index and metadata store · `search-engine-nodejs-server/getting-started/chroma.sqlite3`
- [Index files](https://github.com/sjain022/calhacks/blob/main/search-engine-nodejs-server/getting-started/69b53940-864f-45e4-bd43-0b8dbe0841cd/data_level0.bin): vector artifacts · Stored ANN index shards and graph data · `search-engine-nodejs-server/getting-started/69b53940-864f-45e4-bd43-0b8dbe0841cd/data_level0.bin`

### External APIs

Third-party chess and AI services

- **AI services**: llm/chess apis · Google Gemini, Rapid Chess API, Llama API, and Groq API integrations

## Connections

- React app → Navbar: renders · App shell provides shared navigation
- React app → Login: routes to · Authentication entry flow
- React app → Choose: routes to · Workflow selection flow
- React app → Upload/Search: routes to · Upload or query flow
- React app → Search: routes to · Search results flow
- React app → Train: routes to · Training flow
- React app → Analyze: routes to · Analysis flow
- Analyze → Chess board: uses · Board visualization and move review
- Analyze → Coach chat: uses · Interactive feedback and tutoring chat
- Upload/Search → Flask API: analyzes games · Submits uploaded or fetched Lichess games for evaluation
- Analyze → Flask API: requests feedback · Fetches move analysis and tutoring output
- Train → Flask API: generates puzzles · Uses analysis output to create training material
- Flask API → Analysis core: delegates · Core domain logic is implemented in helper methods
- Analysis core → AI services: calls · Uses external chess and language-model services
- Search → Search API: queries · Search UI sends semantic retrieval requests
- Upload/Search → Search API: searches · Upload/search workflow can query similarity results
- Search API → Chroma store: reads/writes · Primary persistent vector datastore
- Search API → Index files: uses · ANN index artifacts backing retrieval
