# noteworthy-team26-27/ai-study-companion architecture

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

- Interactive diagram: https://gitdiagram.com/noteworthy-team26-27/ai-study-companion
- Repository: https://github.com/noteworthy-team26-27/ai-study-companion

## Overview

AI Study Companion is a PDF-based study app. A browser uploads a typed PDF; the server extracts and stores passages, then supports passage-grounded questions and generated quizzes. Quiz answers are graded deterministically and saved as anonymous, browser-specific progress. The graph also includes the documented keyword/embedding retrieval and model-provider capabilities. Some server initialization and request-handling code is unsampled, so relationships supported only by the README are cited there; uncertain wiring is omitted.

Main entry points: [`noteworthy_app/server.py`](https://github.com/noteworthy-team26-27/ai-study-companion/blob/main/noteworthy_app/server.py) (HTTP API), [`noteworthy_app/attempts.py`](https://github.com/noteworthy-team26-27/ai-study-companion/blob/main/noteworthy_app/attempts.py) (Saved attempts), [`noteworthy_app/question_generator.py`](https://github.com/noteworthy-team26-27/ai-study-companion/blob/main/noteworthy_app/question_generator.py) (AI question generation), [`noteworthy_app/models.py`](https://github.com/noteworthy-team26-27/ai-study-companion/blob/main/noteworthy_app/models.py) (Model adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["PDF ingestion"]
  node_extract["PDF extraction<br/>[core.py]"]
  node_passages["Passages<br/>[core.py]"]
end

subgraph group_study["Study and retrieval"]
  node_web["Study UI<br/>[index.html]"]
  node_server["HTTP API<br/>[server.py]"]
  node_search["Passage retrieval<br/>[search.py]"]
  node_answer["Answer prompting<br/>[core.py]"]
end

subgraph group_assessment["Quizzes and progress"]
  node_questiongen["AI question generation"]
  node_cloze["Cloze fallback<br/>[quiz.py]"]
  node_grading["Answer grading<br/>[grading.py]"]
  node_progress["Progress aggregation<br/>[attempts.py]"]
end

subgraph group_infra["Persistence and inference"]
  node_docstore[("Document store<br/>[storage.py]")]
  node_model["Model adapters<br/>[models.py]"]
  node_quizstore[("Issued quizzes<br/>[attempts.py]")]
  node_attempts[("Saved attempts<br/>[attempts.py]")]
end

node_learner(("Learner browser"))
node_inference["Configured model service"]

node_learner -->|"uses"| node_web
node_web -->|"sends requests"| node_server
node_server -->|"extracts PDF"| node_extract
node_extract -->|"produces"| node_passages
node_server -->|"loads documents"| node_docstore
node_server -->|"saves uploads"| node_docstore
node_server -->|"retrieves passages"| node_search
node_search -->|"ranks"| node_passages
node_server -->|"builds answer context"| node_answer
node_answer -.->|"requests answer"| node_model
node_model -->|"calls provider"| node_inference
node_server -->|"generates quiz"| node_questiongen
node_questiongen -->|"selects source text"| node_passages
node_questiongen -.->|"requests questions"| node_model
node_questiongen -->|"uses fallback"| node_cloze
node_server -->|"issues quiz"| node_quizstore
node_learner -->|"submits answers"| node_server
node_server -->|"submits attempt"| node_attempts
node_attempts -->|"reads quiz"| node_quizstore
node_attempts -->|"grades answers"| node_grading
node_attempts -->|"saves result"| node_attempts
node_server -->|"requests progress"| node_progress
node_progress -->|"aggregates saved scores"| node_attempts

click node_web "https://github.com/noteworthy-team26-27/ai-study-companion/blob/main/noteworthy_app/static/index.html"
click node_server "https://github.com/noteworthy-team26-27/ai-study-companion/blob/main/noteworthy_app/server.py"
click node_extract "https://github.com/noteworthy-team26-27/ai-study-companion/blob/main/noteworthy_app/core.py"
click node_passages "https://github.com/noteworthy-team26-27/ai-study-companion/blob/main/noteworthy_app/core.py"
click node_docstore "https://github.com/noteworthy-team26-27/ai-study-companion/blob/main/noteworthy_app/storage.py"
click node_search "https://github.com/noteworthy-team26-27/ai-study-companion/blob/main/noteworthy_app/search.py"
click node_answer "https://github.com/noteworthy-team26-27/ai-study-companion/blob/main/noteworthy_app/core.py"
click node_model "https://github.com/noteworthy-team26-27/ai-study-companion/blob/main/noteworthy_app/models.py"
click node_questiongen "https://github.com/noteworthy-team26-27/ai-study-companion/blob/main/noteworthy_app/question_generator.py"
click node_cloze "https://github.com/noteworthy-team26-27/ai-study-companion/blob/main/noteworthy_app/quiz.py"
click node_quizstore "https://github.com/noteworthy-team26-27/ai-study-companion/blob/main/noteworthy_app/attempts.py"
click node_grading "https://github.com/noteworthy-team26-27/ai-study-companion/blob/main/noteworthy_app/grading.py"
click node_attempts "https://github.com/noteworthy-team26-27/ai-study-companion/blob/main/noteworthy_app/attempts.py"
click node_progress "https://github.com/noteworthy-team26-27/ai-study-companion/blob/main/noteworthy_app/attempts.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_extract,node_passages,node_learner toneBlue
class node_web,node_server,node_search,node_answer toneAmber
class node_questiongen,node_cloze,node_grading,node_progress toneMint
class node_docstore,node_model,node_quizstore,node_attempts toneRose
class node_inference toneIndigo
```

## Components

### PDF ingestion

- [PDF extraction](https://github.com/noteworthy-team26-27/ai-study-companion/blob/main/noteworthy_app/core.py): `noteworthy_app/core.py`
- [Passages](https://github.com/noteworthy-team26-27/ai-study-companion/blob/main/noteworthy_app/core.py): `noteworthy_app/core.py`

### Study and retrieval

- [Study UI](https://github.com/noteworthy-team26-27/ai-study-companion/blob/main/noteworthy_app/static/index.html): `noteworthy_app/static/index.html`
- [HTTP API](https://github.com/noteworthy-team26-27/ai-study-companion/blob/main/noteworthy_app/server.py): `noteworthy_app/server.py`
- [Passage retrieval](https://github.com/noteworthy-team26-27/ai-study-companion/blob/main/noteworthy_app/search.py): `noteworthy_app/search.py`
- [Answer prompting](https://github.com/noteworthy-team26-27/ai-study-companion/blob/main/noteworthy_app/core.py): `noteworthy_app/core.py`

### Quizzes and progress

- [AI question generation](https://github.com/noteworthy-team26-27/ai-study-companion/blob/main/noteworthy_app/question_generator.py): `noteworthy_app/question_generator.py`
- [Cloze fallback](https://github.com/noteworthy-team26-27/ai-study-companion/blob/main/noteworthy_app/quiz.py): `noteworthy_app/quiz.py`
- [Answer grading](https://github.com/noteworthy-team26-27/ai-study-companion/blob/main/noteworthy_app/grading.py): `noteworthy_app/grading.py`
- [Progress aggregation](https://github.com/noteworthy-team26-27/ai-study-companion/blob/main/noteworthy_app/attempts.py): `noteworthy_app/attempts.py`

### Persistence and inference

- [Document store](https://github.com/noteworthy-team26-27/ai-study-companion/blob/main/noteworthy_app/storage.py): `noteworthy_app/storage.py`
- [Model adapters](https://github.com/noteworthy-team26-27/ai-study-companion/blob/main/noteworthy_app/models.py): `noteworthy_app/models.py`
- [Issued quizzes](https://github.com/noteworthy-team26-27/ai-study-companion/blob/main/noteworthy_app/attempts.py): `noteworthy_app/attempts.py`
- [Saved attempts](https://github.com/noteworthy-team26-27/ai-study-companion/blob/main/noteworthy_app/attempts.py): `noteworthy_app/attempts.py`

### Other components

- **Learner browser**
- **Configured model service**

## Connections

- Learner browser → Study UI: uses (evidence: `README.md`)
- Study UI → HTTP API: sends requests (evidence: `README.md`)
- HTTP API → PDF extraction: extracts PDF (evidence: `README.md`)
- PDF extraction → Passages: produces (evidence: `noteworthy_app/core.py`)
- HTTP API → Document store: loads documents (evidence: `noteworthy_app/server.py`)
- HTTP API → Document store: saves uploads (evidence: `README.md`)
- HTTP API → Passage retrieval: retrieves passages (evidence: `noteworthy_app/server.py`)
- Passage retrieval → Passages: ranks (evidence: `noteworthy_app/search.py`)
- HTTP API → Answer prompting: builds answer context (evidence: `noteworthy_app/core.py`)
- Answer prompting → Model adapters: requests answer
- Model adapters → Configured model service: calls provider (evidence: `README.md`)
- HTTP API → AI question generation: generates quiz (evidence: `noteworthy_app/server.py`)
- AI question generation → Passages: selects source text (evidence: `noteworthy_app/question_generator.py`)
- AI question generation → Model adapters: requests questions
- AI question generation → Cloze fallback: uses fallback (evidence: `noteworthy_app/question_generator.py`)
- HTTP API → Issued quizzes: issues quiz (evidence: `noteworthy_app/server.py`)
- Learner browser → HTTP API: submits answers (evidence: `README.md`)
- HTTP API → Saved attempts: submits attempt (evidence: `noteworthy_app/server.py`)
- Saved attempts → Issued quizzes: reads quiz (evidence: `noteworthy_app/attempts.py`)
- Saved attempts → Answer grading: grades answers (evidence: `noteworthy_app/attempts.py`)
- Saved attempts → Saved attempts: saves result (evidence: `noteworthy_app/attempts.py`)
- HTTP API → Progress aggregation: requests progress (evidence: `noteworthy_app/server.py`)
- Progress aggregation → Saved attempts: aggregates saved scores (evidence: `README.md`)
