How sjain022/calhacks works
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: main.jsx React app · Analyze.jsx Analyze · server.js Search API · app.py Flask API
Components 16
Frontend
React Vite UI and route-level screens
- React app · User-facing chess tutor interface and workflow orchestration
frontend/src/main.jsx - Navbar · Shared navigation and top-level screen framing
frontend/src/app/Navbar.jsx - Login · Authentication entry screen
frontend/src/app/Login.jsx - Choose · Workflow selection screen
frontend/src/app/Choose.jsx - Upload/Search · Game upload and search entry screen
frontend/src/app/UploadSearch.jsx - Search · Semantic search results screen
frontend/src/app/Search.jsx - Train · Training and puzzle workflow screen
frontend/src/app/Train.jsx - Analyze · Game analysis and feedback screen
frontend/src/app/Analyze.jsx - Chess board · Interactive board and move visualization
frontend/src/app/components/ChessGame.jsx - Coach chat · Conversational feedback and tutoring panel
frontend/src/app/components/ChessGameChat.jsx
Python API
Flask tutoring and analysis service
- Flask API · Main analysis and tutoring API boundary
backend/app.py - Analysis core · Game evaluation, tutoring, and puzzle generation logic
backend/methods.py
Search Service
Node.js semantic retrieval layer
- Search API · Semantic search service for chess games and patterns
search-engine-nodejs-server/server.js
Vector Store
Chroma persistence and indexed artifacts
- Chroma store · Persistent vector index and metadata store
search-engine-nodejs-server/getting-started/chroma.sqlite3 - Index files · 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 · Google Gemini, Rapid Chess API, Llama API, and Groq API integrations
Connections 18
- 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