# gervantt/study-helper architecture

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

- Interactive diagram: https://gitdiagram.com/gervantt/study-helper
- Repository: https://github.com/gervantt/study-helper

## Overview

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: [`backend/main.py`](https://github.com/gervantt/study-helper/blob/main/backend/main.py) (FastAPI app), [`frontend/index.html`](https://github.com/gervantt/study-helper/blob/main/frontend/index.html) (React UI), [`run.sh`](https://github.com/gervantt/study-helper/blob/main/run.sh) (run.sh), [`backend/requirements.txt`](https://github.com/gervantt/study-helper/blob/main/backend/requirements.txt) (Python deps)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_frontend_shell["React UI<br/>single-file SPA<br/>[index.html]"]
end

subgraph group_backend["Backend"]
  node_backend_app["FastAPI app<br/>server core<br/>[main.py]"]
  node_backend_requirements["Python deps<br/>runtime config<br/>[requirements.txt]"]
  node_quiz_api(("Quiz API<br/>study endpoint"))
  node_explain_api(("Explain API<br/>study endpoint"))
  node_check_api(("Check API<br/>study endpoint"))
  node_flashcards_api(("Flashcards API<br/>study endpoint"))
  node_chat_api(("Chat API<br/>study endpoint"))
  node_health_api(("Health API<br/>ops endpoint"))
  node_prompt_layer["Prompting<br/>Gemini orchestration"]
end

subgraph group_external["External"]
  node_gemini_service[("Gemini 2.0 Flash<br/>external AI")]
end

subgraph group_launch["Launch"]
  node_run_script["run.sh<br/>startup script<br/>[run.sh]"]
end

node_run_script -->|"starts"| node_backend_app
node_run_script -->|"serves"| node_frontend_shell
node_frontend_shell -->|"request"| node_quiz_api
node_frontend_shell -->|"request"| node_explain_api
node_frontend_shell -->|"request"| node_check_api
node_frontend_shell -->|"request"| node_flashcards_api
node_frontend_shell -->|"request"| node_chat_api
node_frontend_shell -->|"polls"| node_health_api
node_backend_app -->|"routes"| node_quiz_api
node_backend_app -->|"routes"| node_explain_api
node_backend_app -->|"routes"| node_check_api
node_backend_app -->|"routes"| node_flashcards_api
node_backend_app -->|"routes"| node_chat_api
node_backend_app -->|"routes"| node_health_api
node_backend_app -->|"orchestrates"| node_prompt_layer
node_prompt_layer -->|"calls"| node_gemini_service
node_quiz_api -->|"uses"| node_gemini_service
node_explain_api -->|"uses"| node_gemini_service
node_check_api -->|"uses"| node_gemini_service
node_flashcards_api -->|"uses"| node_gemini_service
node_chat_api -->|"uses"| node_gemini_service
node_backend_requirements -->|"depends on"| node_backend_app

click node_run_script "https://github.com/gervantt/study-helper/blob/main/run.sh"
click node_frontend_shell "https://github.com/gervantt/study-helper/blob/main/frontend/index.html"
click node_backend_app "https://github.com/gervantt/study-helper/blob/main/backend/main.py"
click node_backend_requirements "https://github.com/gervantt/study-helper/blob/main/backend/requirements.txt"

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_shell toneBlue
class node_backend_app,node_backend_requirements,node_quiz_api,node_explain_api,node_check_api,node_flashcards_api,node_chat_api,node_health_api,node_prompt_layer toneAmber
class node_gemini_service toneMint
class node_run_script toneRose
```

## Components

### Client

Browser-side study interface

- [React UI](https://github.com/gervantt/study-helper/blob/main/frontend/index.html): single-file SPA · Browser app built in one HTML file · `frontend/index.html`

### Backend

FastAPI server and study routes

- [FastAPI app](https://github.com/gervantt/study-helper/blob/main/backend/main.py): server core · Main Python application and request orchestrator · `backend/main.py`
- [Python deps](https://github.com/gervantt/study-helper/blob/main/backend/requirements.txt): runtime config · Backend package dependencies · `backend/requirements.txt`
- **Quiz API**: study endpoint · Generates quiz questions
- **Explain API**: study endpoint · Produces topic explanations in multiple styles
- **Check API**: study endpoint · Evaluates submitted answers
- **Flashcards API**: study endpoint · Generates flashcard sets
- **Chat API**: study endpoint · Conversational tutor endpoint
- **Health API**: ops endpoint · Operational status check
- **Prompting**: Gemini orchestration · Builds prompts and shapes responses

### External

Third-party AI provider

- **Gemini 2.0 Flash**: external AI · Server-side model provider

### Launch

Local startup entrypoint

- [run.sh](https://github.com/gervantt/study-helper/blob/main/run.sh): startup script · Local launch entrypoint · `run.sh`

## Connections

- 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
