How gervantt/study-helper works
1. Overall shape
- This is a small two-tier application: a Python/FastAPI backend and a single-file React frontend.
- There is no separate database or worker tier in the repo, so the main architectural boundary is browser UI ↔ backend API ↔ external Gemini service.
2. Startup and hosting
- run.sh is the entry point for local use.
- The app is expected to run on localhost:8000, with the backend likely serving both the API and the frontend shell from the same origin.
3. Frontend subsystem
- frontend/index.html is the entire client app.
- It uses React 18, Babel in the browser, and marked.js for rendering formatted AI output.
- Because it is a single HTML file, the frontend is likely a lightweight SPA that sends requests directly to the backend endpoints.
4. Backend subsystem
- backend/main.py is the core server file.
- It provides the FastAPI application, request handling, and all integration with Google Gemini.
- backend/requirements.txt indicates a Python-only backend stack with FastAPI and Google generative AI libraries.
5. AI integration boundary
- The backend is the only component that talks to Google Gemini 2.0 Flash.
- The API key is supplied via GEMINI_API_KEY, so the model access boundary stays server-side rather than exposed to the browser.
6. Primary functional APIs
- The backend exposes distinct endpoints for each study feature:
- /api/quiz for quiz generation
- /api/explain for topic explanations
- /api/check-answer for answer evaluation
- /api/flashcards for flashcard generation
- /api/chat for conversational tutoring
- /api/health for operational checks
- In diagram terms, each frontend action maps to one of these backend routes.
7. Data flow for study generation
- User enters a topic or question in the browser.
- The frontend posts a request to the relevant FastAPI endpoint.
- The backend builds a prompt, calls Gemini, and returns structured text/JSON for the UI to render.
- The frontend then formats that response into quiz cards, explanations, flashcards, or chat messages.
8. Quiz and answer-checking flow
- Quiz creation is a two-step interaction: generate questions first, then validate user responses through /api/check-answer.
- This suggests the backend owns the evaluation logic or model-assisted grading, rather than the frontend performing local scoring.
9. Explanation and tutoring flow
- /api/explain supports multiple explanation styles described in the README: Simple, Detailed, ELI5, Analogy.
- /api/chat is the most open-ended path and functions as a general study assistant, but still routes through the same backend-to-Gemini pipeline.
10. Flashcard flow
- /api/flashcards returns study cards for a topic.
- The frontend likely renders these as flip cards or paired prompt/answer blocks, with the content generated server-side by Gemini.
11. Operational characteristics
- The repository does not show persistent storage, authentication, or user accounts.
- That means the app is likely stateless per request: each user action generates a fresh model call and response, with minimal backend state.
12. Technology boundaries to show in a diagram
- Client layer: React UI in the browser.
- Server layer: FastAPI routes and prompt orchestration.
- External dependency: Google Gemini API.
- Local launch: run.sh and environment variable configuration for the API key.
13. Implication for architecture diagrams
- The cleanest diagram is a single web client connected to one FastAPI backend, with the backend branching into several study endpoints and one external AI provider.
- There are no additional subsystems visible in the repo such as databases, queues, caches, or background jobs.
Main entry points: main.py FastAPI app · index.html React UI · run.sh run.sh · requirements.txt Python deps
Components 12
Backend
FastAPI server and study routes
- FastAPI app · Main Python application and request orchestrator
backend/main.py - Python deps · Backend package dependencies
backend/requirements.txt - Quiz API · Generates quiz questions
- Explain API · Produces topic explanations in multiple styles
- Check API · Evaluates submitted answers
- Flashcards API · Generates flashcard sets
- Chat API · Conversational tutor endpoint
- Health API · Operational status check
- Prompting · Builds prompts and shapes responses
External
Third-party AI provider
- Gemini 2.0 Flash · Server-side model provider
Connections 22
- run.sh → FastAPI app: starts · Local startup launches the server
- run.sh → React UI: serves · App is accessed from the local web UI
- React UI → Quiz API: request · User asks for generated quiz content
- React UI → Explain API: request · User requests an explanation
- React UI → Check API: request · User submits an answer for evaluation
- React UI → Flashcards API: request · User requests flashcards
- React UI → Chat API: request · User starts a tutoring conversation
- React UI → Health API: polls · UI or tooling checks service availability
- FastAPI app → Quiz API: routes · FastAPI exposes the quiz endpoint
- FastAPI app → Explain API: routes · FastAPI exposes the explain endpoint
- FastAPI app → Check API: routes · FastAPI exposes the answer-check endpoint
- FastAPI app → Flashcards API: routes · FastAPI exposes the flashcards endpoint
- FastAPI app → Chat API: routes · FastAPI exposes the chat endpoint
- FastAPI app → Health API: routes · FastAPI exposes the health endpoint
- FastAPI app → Prompting: orchestrates · Core server code constructs prompts and parses replies
- Prompting → Gemini 2.0 Flash: calls · Backend sends study prompts to Gemini
- Quiz API → Gemini 2.0 Flash: uses · Quiz generation relies on Gemini
- Explain API → Gemini 2.0 Flash: uses · Explanation generation relies on Gemini
- Check API → Gemini 2.0 Flash: uses · Answer grading may use model-assisted evaluation
- Flashcards API → Gemini 2.0 Flash: uses · Flashcard generation relies on Gemini
- Chat API → Gemini 2.0 Flash: uses · Tutor chat is backed by Gemini
- Python deps → FastAPI app: depends on · Python server dependencies support the FastAPI app