# kobloid/crunchai architecture

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

- Interactive diagram: https://gitdiagram.com/kobloid/crunchai
- Repository: https://github.com/kobloid/crunchai

## Overview

CrunchAI turns a student's situation and available time into a prioritized, deadline-aware study plan, then guides focus blocks, replanning, recall checks, and progress tracking. The browser study room is the main workflow; FastAPI routes orchestrate validated planner calls and SQLite persistence. Accounts can claim guest plans and topics, while optional topic notes ground study chat and quizzes. The README documents these capabilities; unsampled route and frontend details are represented only where explicit documentation supports them.

Main entry points: [`app/main.py`](https://github.com/kobloid/crunchai/blob/main/app/main.py) (API routes), [`app/static/js/app.js`](https://github.com/kobloid/crunchai/blob/main/app/static/js/app.js) (Study room), [`app/planner.py`](https://github.com/kobloid/crunchai/blob/main/app/planner.py) (Plan and replan), [`app/db.py`](https://github.com/kobloid/crunchai/blob/main/app/db.py) (Application records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Student experience"]
  node_landing["Landing page<br/>[index.html]"]
  node_studyroom["Study room<br/>[app.js]"]
  node_accountui["Account page<br/>[account.js]"]
  node_authjs["Guest and auth client<br/>[auth.js]"]
  node_progressui["Progress page<br/>[progress.js]"]
end

subgraph group_api["API orchestration"]
  node_fastapi["API routes<br/>[main.py]"]
  node_schemas["Request and result schemas<br/>[models.py]"]
end

subgraph group_planning["Planning and AI"]
  node_planner["Plan and replan<br/>[planner.py]"]
  node_studyai["Chat and recall AI<br/>[planner.py]"]
end

subgraph group_state["Persistence"]
  node_sqlite[("Application records<br/>[db.py]")]
end

node_student(("Student"))
node_gemini["Gemini API"]
node_browserstore[("Guest browser state")]

node_student -->|"opens"| node_landing
node_student -->|"describes situation"| node_studyroom
node_landing -->|"starts planning"| node_studyroom
node_studyroom -->|"requests API"| node_fastapi
node_fastapi -->|"validates with"| node_schemas
node_fastapi -->|"generates or replans"| node_planner
node_fastapi -->|"reads and writes"| node_sqlite
node_planner -->|"validates AI output"| node_schemas
node_planner -.->|"calls"| node_gemini
node_studyroom -->|"saves block outcomes"| node_fastapi
node_fastapi -->|"requests study answers"| node_planner
node_planner -.->|"generates quizzes"| node_gemini
node_studyroom -->|"requests topics and chat"| node_fastapi
node_accountui -->|"submits credentials"| node_authjs
node_authjs -->|"authenticates"| node_fastapi
node_authjs -->|"remembers guest work"| node_browserstore
node_fastapi -->|"stores accounts and sessions"| node_sqlite
node_fastapi -->|"stores topics and prompts"| node_sqlite
node_student -->|"views progress"| node_progressui
node_progressui -->|"loads progress"| node_fastapi
node_fastapi -->|"reads progress records"| node_sqlite

click node_landing "https://github.com/kobloid/crunchai/blob/main/app/static/index.html"
click node_studyroom "https://github.com/kobloid/crunchai/blob/main/app/static/js/app.js"
click node_accountui "https://github.com/kobloid/crunchai/blob/main/app/static/js/account.js"
click node_authjs "https://github.com/kobloid/crunchai/blob/main/app/static/js/auth.js"
click node_progressui "https://github.com/kobloid/crunchai/blob/main/app/static/js/progress.js"
click node_fastapi "https://github.com/kobloid/crunchai/blob/main/app/main.py"
click node_schemas "https://github.com/kobloid/crunchai/blob/main/app/models.py"
click node_planner "https://github.com/kobloid/crunchai/blob/main/app/planner.py"
click node_studyai "https://github.com/kobloid/crunchai/blob/main/app/planner.py"
click node_sqlite "https://github.com/kobloid/crunchai/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_landing,node_studyroom,node_accountui,node_authjs,node_progressui toneBlue
class node_fastapi,node_schemas,node_browserstore toneAmber
class node_planner,node_studyai,node_gemini toneMint
class node_sqlite toneRose
class node_student toneIndigo
```

## Components

### Student experience

- [Landing page](https://github.com/kobloid/crunchai/blob/main/app/static/index.html): `app/static/index.html`
- [Study room](https://github.com/kobloid/crunchai/blob/main/app/static/js/app.js): `app/static/js/app.js`
- [Account page](https://github.com/kobloid/crunchai/blob/main/app/static/js/account.js): `app/static/js/account.js`
- [Guest and auth client](https://github.com/kobloid/crunchai/blob/main/app/static/js/auth.js): `app/static/js/auth.js`
- [Progress page](https://github.com/kobloid/crunchai/blob/main/app/static/js/progress.js): `app/static/js/progress.js`

### API orchestration

- [API routes](https://github.com/kobloid/crunchai/blob/main/app/main.py): `app/main.py`
- [Request and result schemas](https://github.com/kobloid/crunchai/blob/main/app/models.py): `app/models.py`

### Planning and AI

- [Plan and replan](https://github.com/kobloid/crunchai/blob/main/app/planner.py): `app/planner.py`
- [Chat and recall AI](https://github.com/kobloid/crunchai/blob/main/app/planner.py): `app/planner.py`

### Persistence

- [Application records](https://github.com/kobloid/crunchai/blob/main/app/db.py): `app/db.py`

### Other components

- **Student**
- **Gemini API**
- **Guest browser state**

## Connections

- Student → Landing page: opens (evidence: `README.md`)
- Student → Study room: describes situation (evidence: `README.md`)
- Landing page → Study room: starts planning (evidence: `README.md`)
- Study room → API routes: requests API (evidence: `app/static/js/app.js`)
- API routes → Request and result schemas: validates with (evidence: `app/models.py`)
- API routes → Plan and replan: generates or replans (evidence: `app/main.py`)
- API routes → Application records: reads and writes (evidence: `app/main.py`)
- Plan and replan → Request and result schemas: validates AI output (evidence: `app/models.py`)
- Plan and replan → Gemini API: calls
- Study room → API routes: saves block outcomes (evidence: `README.md`)
- API routes → Plan and replan: requests study answers (evidence: `README.md`)
- Plan and replan → Gemini API: generates quizzes
- Study room → API routes: requests topics and chat (evidence: `README.md`)
- Account page → Guest and auth client: submits credentials (evidence: `app/static/js/account.js`)
- Guest and auth client → API routes: authenticates (evidence: `app/static/js/auth.js`)
- Guest and auth client → Guest browser state: remembers guest work (evidence: `app/static/js/auth.js`)
- API routes → Application records: stores accounts and sessions (evidence: `app/main.py`)
- API routes → Application records: stores topics and prompts (evidence: `README.md`)
- Student → Progress page: views progress (evidence: `README.md`)
- Progress page → API routes: loads progress (evidence: `app/static/js/progress.js`)
- API routes → Application records: reads progress records (evidence: `README.md`)