# nikhil-4404/ai-exam-planner architecture

> Architecture diagram of the GitHub repository nikhil-4404/ai-exam-planner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nikhil-4404/ai-exam-planner
- Repository: https://github.com/nikhil-4404/ai-exam-planner

## Overview

This is a browser-based exam preparation planner: users enter exam, subject, and study constraints, receive a generated strategy, and can save plans or export them as PDFs. The FastAPI application coordinates authentication, strategy generation, persistence, and exports; the browser handles forms and renders results. The README also documents theme switching and deterministic fallback behavior. The supplied excerpts show the API, models, database, PDF builder, and parts of the browser scripts; some UI behavior is documented but not fully sampled.

Main entry points: [`app/main.py`](https://github.com/nikhil-4404/ai-exam-planner/blob/main/app/main.py) (FastAPI routes), [`app/static/planner.js`](https://github.com/nikhil-4404/ai-exam-planner/blob/main/app/static/planner.js) (Planner UI), [`app/ai.py`](https://github.com/nikhil-4404/ai-exam-planner/blob/main/app/ai.py) (Strategy engine), [`app/static/auth.js`](https://github.com/nikhil-4404/ai-exam-planner/blob/main/app/static/auth.js) (Login UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Browser interface"]
  node_browser["Browser"]
  node_auth_ui["Login UI<br/>[auth.js]"]
  node_planner_ui["Planner UI<br/>[planner.js]"]
  node_templates["Page templates"]
end

subgraph group_api["API coordination"]
  node_api_app["FastAPI routes<br/>[main.py]"]
  node_schemas["Request and response models<br/>[models.py]"]
end

subgraph group_strategy["Strategy generation"]
  node_strategy_engine["Strategy engine<br/>[ai.py]"]
  node_groq["Groq Chat Completions"]
end

subgraph group_data["Plans and exports"]
  node_pdf_builder["PDF builder<br/>[pdf.py]"]
  node_db_access["SQLite access<br/>[db.py]"]
  node_sqlite[("Planner database")]
end

node_user(("Planner user"))

node_user -->|"uses"| node_browser
node_browser -->|"loads"| node_auth_ui
node_browser -->|"loads"| node_planner_ui
node_api_app -->|"renders"| node_templates
node_api_app -->|"serves pages"| node_browser
node_browser -->|"sends requests"| node_api_app
node_auth_ui -->|"authenticates"| node_api_app
node_planner_ui -->|"requests strategy"| node_api_app
node_api_app -->|"generates strategy"| node_strategy_engine
node_strategy_engine -.->|"requests completion"| node_groq
node_strategy_engine -->|"returns strategy"| node_api_app
node_api_app -->|"uses models"| node_schemas
node_api_app -->|"reads and writes"| node_db_access
node_db_access -->|"queries"| node_sqlite
node_api_app -->|"builds export"| node_pdf_builder
node_api_app -->|"streams PDF"| node_browser
node_planner_ui -->|"manages saved plans"| node_api_app

click node_auth_ui "https://github.com/nikhil-4404/ai-exam-planner/blob/main/app/static/auth.js"
click node_planner_ui "https://github.com/nikhil-4404/ai-exam-planner/blob/main/app/static/planner.js"
click node_templates "https://github.com/nikhil-4404/ai-exam-planner/tree/main/app/templates"
click node_api_app "https://github.com/nikhil-4404/ai-exam-planner/blob/main/app/main.py"
click node_schemas "https://github.com/nikhil-4404/ai-exam-planner/blob/main/app/models.py"
click node_strategy_engine "https://github.com/nikhil-4404/ai-exam-planner/blob/main/app/ai.py"
click node_pdf_builder "https://github.com/nikhil-4404/ai-exam-planner/blob/main/app/pdf.py"
click node_db_access "https://github.com/nikhil-4404/ai-exam-planner/blob/main/app/db.py"

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_browser,node_auth_ui,node_planner_ui,node_templates,node_user toneBlue
class node_api_app,node_schemas toneAmber
class node_strategy_engine,node_groq toneMint
class node_pdf_builder,node_db_access,node_sqlite toneRose
```

## Components

### Browser interface

- **Browser**
- [Login UI](https://github.com/nikhil-4404/ai-exam-planner/blob/main/app/static/auth.js): `app/static/auth.js`
- [Planner UI](https://github.com/nikhil-4404/ai-exam-planner/blob/main/app/static/planner.js): `app/static/planner.js`
- [Page templates](https://github.com/nikhil-4404/ai-exam-planner/tree/main/app/templates): `app/templates`

### API coordination

- [FastAPI routes](https://github.com/nikhil-4404/ai-exam-planner/blob/main/app/main.py): `app/main.py`
- [Request and response models](https://github.com/nikhil-4404/ai-exam-planner/blob/main/app/models.py): `app/models.py`

### Strategy generation

- [Strategy engine](https://github.com/nikhil-4404/ai-exam-planner/blob/main/app/ai.py): `app/ai.py`
- **Groq Chat Completions**

### Plans and exports

- [PDF builder](https://github.com/nikhil-4404/ai-exam-planner/blob/main/app/pdf.py): `app/pdf.py`
- [SQLite access](https://github.com/nikhil-4404/ai-exam-planner/blob/main/app/db.py): `app/db.py`
- **Planner database**

### Other components

- **Planner user**

## Connections

- Planner user → Browser: uses
- Browser → Login UI: loads
- Browser → Planner UI: loads
- FastAPI routes → Page templates: renders
- FastAPI routes → Browser: serves pages
- Browser → FastAPI routes: sends requests
- Login UI → FastAPI routes: authenticates
- Planner UI → FastAPI routes: requests strategy
- FastAPI routes → Strategy engine: generates strategy
- Strategy engine → Groq Chat Completions: requests completion
- Strategy engine → FastAPI routes: returns strategy
- FastAPI routes → Request and response models: uses models
- FastAPI routes → SQLite access: reads and writes
- SQLite access → Planner database: queries
- FastAPI routes → PDF builder: builds export
- FastAPI routes → Browser: streams PDF
- Planner UI → FastAPI routes: manages saved plans