# odahabb/student-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/odahabb/student-assistant
- Repository: https://github.com/odahabb/student-assistant

## Overview

This is a local multimodal study assistant: students add course material to a subject, ask questions grounded in its indexed passages, and practise topic quizzes that update mastery and revision recommendations. The main path runs from the browser through the API and service into document loading, chunking, embedding and indexing; questions then retrieve passages and generate streamed answers. Quiz and progress are distinct learning stages over the shared index. The README documents major capabilities, but service and frontend excerpts are partial, so uncertain internal call wiring is omitted.

Main entry points: [`backend/service.py`](https://github.com/odahabb/student-assistant/blob/main/backend/service.py) (Application service), [`backend/pipeline/retriever.py`](https://github.com/odahabb/student-assistant/blob/main/backend/pipeline/retriever.py) (Hybrid retrieval), [`backend/pipeline/quiz.py`](https://github.com/odahabb/student-assistant/blob/main/backend/pipeline/quiz.py) (Quiz generation and grading), [`backend/pipeline/embedder.py`](https://github.com/odahabb/student-assistant/blob/main/backend/pipeline/embedder.py) (Text embedder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_frontend["Browser interface<br/>[app.js]"]
  node_api["FastAPI routes<br/>[api.py]"]
  node_service["Application service<br/>[service.py]"]
end

subgraph group_indexing["Material indexing"]
  node_loader["Multimodal loader<br/>[loader.py]"]
  node_preprocessor["Clean and chunk<br/>[preprocessor.py]"]
  node_chunk["Chunk metadata<br/>[chunk.py]"]
  node_embedder["Text embedder<br/>[embedder.py]"]
  node_vectorstore[("FAISS index<br/>[vector_store.py]")]
  node_sparse[("BM25 index<br/>[sparse.py]")]
end

subgraph group_answers["Question answering"]
  node_retriever["Hybrid retrieval<br/>[retriever.py]"]
  node_generator["Answer generator<br/>[generator.py]"]
end

subgraph group_learning["Quiz and progress"]
  node_quiz["Quiz generation and grading<br/>[quiz.py]"]
  node_recommender["Mastery and revision<br/>[recommender.py]"]
end

subgraph group_state["Subject state"]
  node_workspace[("Subject files and records<br/>[service.py]")]
end

node_student(("Student"))
node_localmodels["Local model runtimes"]

node_student -->|"uses"| node_frontend
node_frontend -->|"requests"| node_api
node_api -->|"dispatches"| node_service
node_service -->|"reads and writes"| node_workspace
node_service -->|"loads material"| node_loader
node_loader -.->|"reads images and audio"| node_localmodels
node_service -->|"chunks content"| node_preprocessor
node_preprocessor -->|"creates chunks"| node_chunk
node_service -->|"embeds chunks"| node_embedder
node_embedder -.->|"encodes text"| node_localmodels
node_service -->|"builds index"| node_vectorstore
node_service -->|"builds keyword index"| node_sparse
node_service -->|"retrieves passages"| node_retriever
node_retriever -->|"embeds query"| node_embedder
node_retriever -->|"searches dense index"| node_vectorstore
node_retriever -->|"scores keywords"| node_sparse
node_service -->|"generates answer"| node_generator
node_generator -.->|"generates text"| node_localmodels
node_service -->|"handles quiz"| node_quiz
node_quiz -->|"writes and checks questions"| node_generator
node_quiz -->|"checks retrieval support"| node_retriever
node_service -->|"updates mastery"| node_recommender
node_service -->|"supplies question context"| node_retriever

click node_frontend "https://github.com/odahabb/student-assistant/blob/main/frontend/app.js"
click node_api "https://github.com/odahabb/student-assistant/blob/main/backend/api.py"
click node_service "https://github.com/odahabb/student-assistant/blob/main/backend/service.py"
click node_workspace "https://github.com/odahabb/student-assistant/blob/main/backend/service.py"
click node_loader "https://github.com/odahabb/student-assistant/blob/main/backend/pipeline/loader.py"
click node_preprocessor "https://github.com/odahabb/student-assistant/blob/main/backend/pipeline/preprocessor.py"
click node_chunk "https://github.com/odahabb/student-assistant/blob/main/backend/pipeline/chunk.py"
click node_embedder "https://github.com/odahabb/student-assistant/blob/main/backend/pipeline/embedder.py"
click node_vectorstore "https://github.com/odahabb/student-assistant/blob/main/backend/pipeline/vector_store.py"
click node_sparse "https://github.com/odahabb/student-assistant/blob/main/backend/pipeline/sparse.py"
click node_retriever "https://github.com/odahabb/student-assistant/blob/main/backend/pipeline/retriever.py"
click node_generator "https://github.com/odahabb/student-assistant/blob/main/backend/pipeline/generator.py"
click node_quiz "https://github.com/odahabb/student-assistant/blob/main/backend/pipeline/quiz.py"
click node_recommender "https://github.com/odahabb/student-assistant/blob/main/backend/pipeline/recommender.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_frontend,node_api,node_service toneBlue
class node_loader,node_preprocessor,node_chunk,node_embedder,node_vectorstore,node_sparse toneAmber
class node_retriever,node_generator toneMint
class node_quiz,node_recommender toneRose
class node_workspace,node_student,node_localmodels toneIndigo
```

## Components

### Web application

- [Browser interface](https://github.com/odahabb/student-assistant/blob/main/frontend/app.js): `frontend/app.js`
- [FastAPI routes](https://github.com/odahabb/student-assistant/blob/main/backend/api.py): `backend/api.py`
- [Application service](https://github.com/odahabb/student-assistant/blob/main/backend/service.py): `backend/service.py`

### Material indexing

- [Multimodal loader](https://github.com/odahabb/student-assistant/blob/main/backend/pipeline/loader.py): `backend/pipeline/loader.py`
- [Clean and chunk](https://github.com/odahabb/student-assistant/blob/main/backend/pipeline/preprocessor.py): `backend/pipeline/preprocessor.py`
- [Chunk metadata](https://github.com/odahabb/student-assistant/blob/main/backend/pipeline/chunk.py): `backend/pipeline/chunk.py`
- [Text embedder](https://github.com/odahabb/student-assistant/blob/main/backend/pipeline/embedder.py): `backend/pipeline/embedder.py`
- [FAISS index](https://github.com/odahabb/student-assistant/blob/main/backend/pipeline/vector_store.py): `backend/pipeline/vector_store.py`
- [BM25 index](https://github.com/odahabb/student-assistant/blob/main/backend/pipeline/sparse.py): `backend/pipeline/sparse.py`

### Question answering

- [Hybrid retrieval](https://github.com/odahabb/student-assistant/blob/main/backend/pipeline/retriever.py): `backend/pipeline/retriever.py`
- [Answer generator](https://github.com/odahabb/student-assistant/blob/main/backend/pipeline/generator.py): `backend/pipeline/generator.py`

### Quiz and progress

- [Quiz generation and grading](https://github.com/odahabb/student-assistant/blob/main/backend/pipeline/quiz.py): `backend/pipeline/quiz.py`
- [Mastery and revision](https://github.com/odahabb/student-assistant/blob/main/backend/pipeline/recommender.py): `backend/pipeline/recommender.py`

### Subject state

- [Subject files and records](https://github.com/odahabb/student-assistant/blob/main/backend/service.py): `backend/service.py`

### Other components

- **Student**
- **Local model runtimes**

## Connections

- Student → Browser interface: uses
- Browser interface → FastAPI routes: requests
- FastAPI routes → Application service: dispatches
- Application service → Subject files and records: reads and writes
- Application service → Multimodal loader: loads material
- Multimodal loader → Local model runtimes: reads images and audio
- Application service → Clean and chunk: chunks content
- Clean and chunk → Chunk metadata: creates chunks
- Application service → Text embedder: embeds chunks
- Text embedder → Local model runtimes: encodes text
- Application service → FAISS index: builds index
- Application service → BM25 index: builds keyword index
- Application service → Hybrid retrieval: retrieves passages
- Hybrid retrieval → Text embedder: embeds query
- Hybrid retrieval → FAISS index: searches dense index
- Hybrid retrieval → BM25 index: scores keywords
- Application service → Answer generator: generates answer
- Answer generator → Local model runtimes: generates text
- Application service → Quiz generation and grading: handles quiz
- Quiz generation and grading → Answer generator: writes and checks questions
- Quiz generation and grading → Hybrid retrieval: checks retrieval support
- Application service → Mastery and revision: updates mastery
- Application service → Hybrid retrieval: supplies question context