# mahikushwaha/studypilot architecture

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

- Interactive diagram: https://gitdiagram.com/mahikushwaha/studypilot
- Repository: https://github.com/mahikushwaha/studypilot

## Overview

StudyPilot is a Flask study-planning app. Students use its web interface to set up subjects and syllabus, plan around exams, and review next steps; the backend can calculate readiness and daily study hours, negotiate a realistic target, and provide a readiness report. The README also describes accounts, persistent preferences and topics, chat memory, and retrieval over study tips and pending topics. The available source excerpt covers agent behavior, but not Flask routes or storage implementation, so those relationships are shown only where the README documents them.

Main entry points: [`static/index.html`](https://github.com/mahikushwaha/studypilot/blob/main/static/index.html) (Study web interface), [`agent.py`](https://github.com/mahikushwaha/studypilot/blob/main/agent.py) (Study agent), [`app.py`](https://github.com/mahikushwaha/studypilot/blob/main/app.py) (Planner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Student experience"]
  node_web["Study web interface<br/>[index.html]"]
  node_guided_setup["Guided setup<br/>[app.py]"]
  node_syllabus["Syllabus input<br/>[app.py]"]
  node_next_steps["Next step cards<br/>[app.py]"]
end

subgraph group_planning["Study planning"]
  node_planner["Planner<br/>[app.py]"]
  node_readiness["Readiness check<br/>[agent.py]"]
  node_hours["Hours calculator<br/>[agent.py]"]
  node_negotiation["Plan negotiation<br/>[agent.py]"]
  node_report["Readiness report<br/>[agent.py]"]
end

subgraph group_intelligence["Agent and retrieval"]
  node_agent["Study agent<br/>[agent.py]"]
  node_retrieval["Study-tip retrieval<br/>[agent.py]"]
  node_topic_retrieval["Pending-topic retrieval<br/>[agent.py]"]
  node_chat_memory["Chat memory<br/>[app.py]"]
  node_model{{"Ollama or OpenRouter"}}
end

subgraph group_accounts["Accounts and persistence"]
  node_account["Account and tokens<br/>[app.py]"]
  node_preferences["Student preferences<br/>[app.py]"]
  node_database[("SQLite or Postgres<br/>[app.py]")]
end

node_student(("Student"))

node_student -->|"uses"| node_web
node_web -->|"supports setup"| node_guided_setup
node_web -->|"uploads or pastes"| node_syllabus
node_web -->|"opens planner"| node_planner
node_planner -->|"shows next steps"| node_next_steps
node_planner -->|"requests planning"| node_agent
node_agent -->|"dispatches tool"| node_readiness
node_agent -->|"dispatches tool"| node_hours
node_planner -->|"negotiates target"| node_negotiation
node_planner -->|"checks plan"| node_report
node_agent -->|"invokes model"| node_model
node_agent -->|"retrieves tips"| node_retrieval
node_agent -->|"retrieves topics"| node_topic_retrieval
node_web -->|"maintains chat"| node_chat_memory
node_web -->|"supports accounts"| node_account
node_account -->|"stores account data"| node_database
node_preferences -->|"stores preferences"| node_database
node_chat_memory -->|"stores memory"| node_database
node_syllabus -->|"stores subjects and topics"| node_database

click node_web "https://github.com/mahikushwaha/studypilot/blob/main/static/index.html"
click node_guided_setup "https://github.com/mahikushwaha/studypilot/blob/main/app.py"
click node_syllabus "https://github.com/mahikushwaha/studypilot/blob/main/app.py"
click node_next_steps "https://github.com/mahikushwaha/studypilot/blob/main/app.py"
click node_planner "https://github.com/mahikushwaha/studypilot/blob/main/app.py"
click node_readiness "https://github.com/mahikushwaha/studypilot/blob/main/agent.py"
click node_hours "https://github.com/mahikushwaha/studypilot/blob/main/agent.py"
click node_negotiation "https://github.com/mahikushwaha/studypilot/blob/main/agent.py"
click node_report "https://github.com/mahikushwaha/studypilot/blob/main/agent.py"
click node_agent "https://github.com/mahikushwaha/studypilot/blob/main/agent.py"
click node_retrieval "https://github.com/mahikushwaha/studypilot/blob/main/agent.py"
click node_topic_retrieval "https://github.com/mahikushwaha/studypilot/blob/main/agent.py"
click node_chat_memory "https://github.com/mahikushwaha/studypilot/blob/main/app.py"
click node_account "https://github.com/mahikushwaha/studypilot/blob/main/app.py"
click node_preferences "https://github.com/mahikushwaha/studypilot/blob/main/app.py"
click node_database "https://github.com/mahikushwaha/studypilot/blob/main/app.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_web,node_guided_setup,node_syllabus,node_next_steps toneBlue
class node_planner,node_readiness,node_hours,node_negotiation,node_report toneAmber
class node_agent,node_retrieval,node_topic_retrieval,node_chat_memory,node_model toneMint
class node_account,node_preferences,node_database toneRose
class node_student toneIndigo
```

## Components

### Student experience

- [Study web interface](https://github.com/mahikushwaha/studypilot/blob/main/static/index.html): `static/index.html`
- [Guided setup](https://github.com/mahikushwaha/studypilot/blob/main/app.py): `app.py`
- [Syllabus input](https://github.com/mahikushwaha/studypilot/blob/main/app.py): `app.py`
- [Next step cards](https://github.com/mahikushwaha/studypilot/blob/main/app.py): `app.py`

### Study planning

- [Planner](https://github.com/mahikushwaha/studypilot/blob/main/app.py): `app.py`
- [Readiness check](https://github.com/mahikushwaha/studypilot/blob/main/agent.py): `agent.py`
- [Hours calculator](https://github.com/mahikushwaha/studypilot/blob/main/agent.py): `agent.py`
- [Plan negotiation](https://github.com/mahikushwaha/studypilot/blob/main/agent.py): `agent.py`
- [Readiness report](https://github.com/mahikushwaha/studypilot/blob/main/agent.py): `agent.py`

### Agent and retrieval

- [Study agent](https://github.com/mahikushwaha/studypilot/blob/main/agent.py): `agent.py`
- [Study-tip retrieval](https://github.com/mahikushwaha/studypilot/blob/main/agent.py): `agent.py`
- [Pending-topic retrieval](https://github.com/mahikushwaha/studypilot/blob/main/agent.py): `agent.py`
- [Chat memory](https://github.com/mahikushwaha/studypilot/blob/main/app.py): `app.py`
- **Ollama or OpenRouter**

### Accounts and persistence

- [Account and tokens](https://github.com/mahikushwaha/studypilot/blob/main/app.py): `app.py`
- [Student preferences](https://github.com/mahikushwaha/studypilot/blob/main/app.py): `app.py`
- [SQLite or Postgres](https://github.com/mahikushwaha/studypilot/blob/main/app.py): `app.py`

### Other components

- **Student**

## Connections

- Student → Study web interface: uses (evidence: `README.md`)
- Study web interface → Guided setup: supports setup (evidence: `README.md`)
- Study web interface → Syllabus input: uploads or pastes (evidence: `README.md`)
- Study web interface → Planner: opens planner (evidence: `README.md`)
- Planner → Next step cards: shows next steps (evidence: `README.md`)
- Planner → Study agent: requests planning (evidence: `README.md`)
- Study agent → Readiness check: dispatches tool (evidence: `agent.py`)
- Study agent → Hours calculator: dispatches tool (evidence: `agent.py`)
- Planner → Plan negotiation: negotiates target (evidence: `README.md`)
- Planner → Readiness report: checks plan (evidence: `README.md`)
- Study agent → Ollama or OpenRouter: invokes model (evidence: `agent.py`)
- Study agent → Study-tip retrieval: retrieves tips (evidence: `README.md`)
- Study agent → Pending-topic retrieval: retrieves topics (evidence: `README.md`)
- Study web interface → Chat memory: maintains chat (evidence: `README.md`)
- Study web interface → Account and tokens: supports accounts (evidence: `README.md`)
- Account and tokens → SQLite or Postgres: stores account data (evidence: `README.md`)
- Student preferences → SQLite or Postgres: stores preferences (evidence: `README.md`)
- Chat memory → SQLite or Postgres: stores memory (evidence: `README.md`)
- Syllabus input → SQLite or Postgres: stores subjects and topics (evidence: `README.md`)
