# sam-se23/se201-project architecture

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

- Interactive diagram: https://gitdiagram.com/sam-se23/se201-project
- Repository: https://github.com/sam-se23/se201-project

## Overview

AI Study Buddy lets students ingest course PDFs/PPTX, ask citation-grounded questions, compare answers with exact-text Ctrl+F, and generate and review quizzes. The Gradio UI delegates actions to a backend orchestrator, which coordinates retrieval, QA, quiz, logging, and document management. Retrieval combines document parsing and chunking with vector and BM25 search. The README documents major behaviors not fully visible in the excerpts; those links are cited to it, while internal links are limited to shown references and calls.

Main entry points: [`backend/orchestrator.py`](https://github.com/sam-se23/se201-project/blob/main/backend/orchestrator.py) (Orchestrator), [`frontend/components.py`](https://github.com/sam-se23/se201-project/blob/main/frontend/components.py) (UI actions), [`backend/retrieval/__init__.py`](https://github.com/sam-se23/se201-project/blob/main/backend/retrieval/__init__.py) (Retriever adapter), [`backend/retrieval/rag-pipeline/pipeline/retrieve.py`](https://github.com/sam-se23/se201-project/blob/main/backend/retrieval/rag-pipeline/pipeline/retrieve.py) (Hybrid retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Student interface"]
  node_gradio_app["Gradio app<br/>[app.py]"]
  node_ui_components["UI actions<br/>[components.py]"]
  node_ui_formatting["Result formatting<br/>[formatting.py]"]
end

subgraph group_coordination["Backend coordination"]
  node_orchestrator["Orchestrator<br/>[orchestrator.py]"]
  node_file_management["Upload management<br/>[files.py]"]
end

subgraph group_retrieval["Document retrieval"]
  node_retriever_adapter["Retriever adapter<br/>[__init__.py]"]
  node_document_ingestion["PDF/PPTX ingestion<br/>[ingest.py]"]
  node_chunking["Chunking and sanitizing<br/>[chunk.py]"]
  node_embeddings["Query embeddings<br/>[embed.py]"]
  node_vector_store[("Vector index<br/>[store.py]")]
  node_bm25_index[("BM25 index<br/>[bm25.py]")]
  node_hybrid_search["Hybrid retrieval<br/>[retrieve.py]"]
end

subgraph group_learning["Learning engines"]
  node_qa_engine["Grounded Q&amp;A<br/>[components.py]"]
  node_qa_prompts["QA prompts and citations<br/>[qa_prompts.py]"]
  node_quiz_engine["Quiz generation and grading<br/>[__init__.py]"]
end

subgraph group_support["Shared services"]
  node_llm_client["LLM client<br/>[__init__.py]"]
  node_ctrl_f["Ctrl+F baseline<br/>[ctrl_f.py]"]
  node_disclosure_log[("AI interaction log<br/>[disclosure_log.py]")]
  node_configuration["Runtime configuration<br/>[config.py]"]
  node_interfaces["Component contracts<br/>[interfaces.py]"]
end

node_student(("Student"))
node_course_files["Course files"]
node_ollama["Ollama or hosted model"]

node_student -->|"uses"| node_gradio_app
node_course_files -->|"uploads"| node_ui_components
node_gradio_app -->|"builds tabs"| node_ui_components
node_ui_components -->|"dispatches actions"| node_orchestrator
node_ui_components -->|"formats results"| node_ui_formatting
node_orchestrator -->|"stores and deletes"| node_file_management
node_orchestrator -->|"ingests and queries"| node_retriever_adapter
node_orchestrator -->|"indexes and searches"| node_ctrl_f
node_orchestrator -->|"answers questions"| node_qa_engine
node_orchestrator -->|"runs quiz actions"| node_quiz_engine
node_orchestrator -->|"records interactions"| node_disclosure_log
node_orchestrator -->|"loads settings"| node_configuration
node_retriever_adapter -->|"parses documents"| node_document_ingestion
node_document_ingestion -->|"feeds text"| node_chunking
node_retriever_adapter -->|"retrieves passages"| node_hybrid_search
node_hybrid_search -->|"embeds query"| node_embeddings
node_hybrid_search -->|"queries index"| node_vector_store
node_hybrid_search -->|"searches keywords"| node_bm25_index
node_qa_engine -->|"retrieves context"| node_retriever_adapter
node_qa_engine -->|"generates answers"| node_llm_client
node_qa_engine -->|"uses grounding rules"| node_qa_prompts
node_quiz_engine -->|"retrieves passages"| node_retriever_adapter
node_quiz_engine -->|"generates questions"| node_llm_client
node_llm_client -->|"calls provider"| node_ollama
node_ui_components -->|"receives results"| node_orchestrator
node_configuration -->|"selects implementations"| node_interfaces

click node_gradio_app "https://github.com/sam-se23/se201-project/blob/main/frontend/app.py"
click node_ui_components "https://github.com/sam-se23/se201-project/blob/main/frontend/components.py"
click node_ui_formatting "https://github.com/sam-se23/se201-project/blob/main/frontend/formatting.py"
click node_orchestrator "https://github.com/sam-se23/se201-project/blob/main/backend/orchestrator.py"
click node_file_management "https://github.com/sam-se23/se201-project/blob/main/backend/files.py"
click node_retriever_adapter "https://github.com/sam-se23/se201-project/blob/main/backend/retrieval/__init__.py"
click node_document_ingestion "https://github.com/sam-se23/se201-project/blob/main/backend/retrieval/rag-pipeline/pipeline/ingest.py"
click node_chunking "https://github.com/sam-se23/se201-project/blob/main/backend/retrieval/rag-pipeline/pipeline/chunk.py"
click node_embeddings "https://github.com/sam-se23/se201-project/blob/main/backend/retrieval/rag-pipeline/pipeline/embed.py"
click node_vector_store "https://github.com/sam-se23/se201-project/blob/main/backend/retrieval/rag-pipeline/pipeline/store.py"
click node_bm25_index "https://github.com/sam-se23/se201-project/blob/main/backend/retrieval/rag-pipeline/pipeline/bm25.py"
click node_hybrid_search "https://github.com/sam-se23/se201-project/blob/main/backend/retrieval/rag-pipeline/pipeline/retrieve.py"
click node_qa_engine "https://github.com/sam-se23/se201-project/blob/main/backend/qa/components.py"
click node_qa_prompts "https://github.com/sam-se23/se201-project/blob/main/backend/qa/qa_prompts.py"
click node_quiz_engine "https://github.com/sam-se23/se201-project/blob/main/backend/quiz/__init__.py"
click node_llm_client "https://github.com/sam-se23/se201-project/blob/main/backend/llm/__init__.py"
click node_ctrl_f "https://github.com/sam-se23/se201-project/blob/main/backend/baseline/ctrl_f.py"
click node_disclosure_log "https://github.com/sam-se23/se201-project/blob/main/backend/disclosure_log.py"
click node_configuration "https://github.com/sam-se23/se201-project/blob/main/backend/config.py"
click node_interfaces "https://github.com/sam-se23/se201-project/blob/main/backend/interfaces.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_gradio_app,node_ui_components,node_ui_formatting toneBlue
class node_orchestrator,node_file_management toneAmber
class node_retriever_adapter,node_document_ingestion,node_chunking,node_embeddings,node_vector_store,node_bm25_index,node_hybrid_search toneMint
class node_qa_engine,node_qa_prompts,node_quiz_engine toneRose
class node_llm_client,node_ctrl_f,node_disclosure_log,node_configuration,node_interfaces,node_student,node_course_files,node_ollama toneIndigo
```

## Components

### Student interface

- [Gradio app](https://github.com/sam-se23/se201-project/blob/main/frontend/app.py): `frontend/app.py`
- [UI actions](https://github.com/sam-se23/se201-project/blob/main/frontend/components.py): `frontend/components.py`
- [Result formatting](https://github.com/sam-se23/se201-project/blob/main/frontend/formatting.py): `frontend/formatting.py`

### Backend coordination

- [Orchestrator](https://github.com/sam-se23/se201-project/blob/main/backend/orchestrator.py): `backend/orchestrator.py`
- [Upload management](https://github.com/sam-se23/se201-project/blob/main/backend/files.py): `backend/files.py`

### Document retrieval

- [Retriever adapter](https://github.com/sam-se23/se201-project/blob/main/backend/retrieval/__init__.py): `backend/retrieval/__init__.py`
- [PDF/PPTX ingestion](https://github.com/sam-se23/se201-project/blob/main/backend/retrieval/rag-pipeline/pipeline/ingest.py): `backend/retrieval/rag-pipeline/pipeline/ingest.py`
- [Chunking and sanitizing](https://github.com/sam-se23/se201-project/blob/main/backend/retrieval/rag-pipeline/pipeline/chunk.py): `backend/retrieval/rag-pipeline/pipeline/chunk.py`
- [Query embeddings](https://github.com/sam-se23/se201-project/blob/main/backend/retrieval/rag-pipeline/pipeline/embed.py): `backend/retrieval/rag-pipeline/pipeline/embed.py`
- [Vector index](https://github.com/sam-se23/se201-project/blob/main/backend/retrieval/rag-pipeline/pipeline/store.py): `backend/retrieval/rag-pipeline/pipeline/store.py`
- [BM25 index](https://github.com/sam-se23/se201-project/blob/main/backend/retrieval/rag-pipeline/pipeline/bm25.py): `backend/retrieval/rag-pipeline/pipeline/bm25.py`
- [Hybrid retrieval](https://github.com/sam-se23/se201-project/blob/main/backend/retrieval/rag-pipeline/pipeline/retrieve.py): `backend/retrieval/rag-pipeline/pipeline/retrieve.py`

### Learning engines

- [Grounded Q&A](https://github.com/sam-se23/se201-project/blob/main/backend/qa/components.py): `backend/qa/components.py`
- [QA prompts and citations](https://github.com/sam-se23/se201-project/blob/main/backend/qa/qa_prompts.py): `backend/qa/qa_prompts.py`
- [Quiz generation and grading](https://github.com/sam-se23/se201-project/blob/main/backend/quiz/__init__.py): `backend/quiz/__init__.py`

### Shared services

- [LLM client](https://github.com/sam-se23/se201-project/blob/main/backend/llm/__init__.py): `backend/llm/__init__.py`
- [Ctrl+F baseline](https://github.com/sam-se23/se201-project/blob/main/backend/baseline/ctrl_f.py): `backend/baseline/ctrl_f.py`
- [AI interaction log](https://github.com/sam-se23/se201-project/blob/main/backend/disclosure_log.py): `backend/disclosure_log.py`
- [Runtime configuration](https://github.com/sam-se23/se201-project/blob/main/backend/config.py): `backend/config.py`
- [Component contracts](https://github.com/sam-se23/se201-project/blob/main/backend/interfaces.py): `backend/interfaces.py`

### Other components

- **Student**
- **Course files**
- **Ollama or hosted model**

## Connections

- Student → Gradio app: uses (evidence: `README.md`)
- Course files → UI actions: uploads (evidence: `README.md`)
- Gradio app → UI actions: builds tabs (evidence: `frontend/app.py`)
- UI actions → Orchestrator: dispatches actions (evidence: `README.md`)
- UI actions → Result formatting: formats results (evidence: `frontend/components.py`)
- Orchestrator → Upload management: stores and deletes (evidence: `backend/orchestrator.py`)
- Orchestrator → Retriever adapter: ingests and queries (evidence: `backend/orchestrator.py`)
- Orchestrator → Ctrl+F baseline: indexes and searches (evidence: `backend/orchestrator.py`)
- Orchestrator → Grounded Q&A: answers questions (evidence: `README.md`)
- Orchestrator → Quiz generation and grading: runs quiz actions (evidence: `README.md`)
- Orchestrator → AI interaction log: records interactions (evidence: `backend/orchestrator.py`)
- Orchestrator → Runtime configuration: loads settings (evidence: `backend/orchestrator.py`)
- Retriever adapter → PDF/PPTX ingestion: parses documents (evidence: `backend/retrieval/__init__.py`)
- PDF/PPTX ingestion → Chunking and sanitizing: feeds text (evidence: `backend/retrieval/rag-pipeline/pipeline/chunk.py`)
- Retriever adapter → Hybrid retrieval: retrieves passages (evidence: `backend/retrieval/__init__.py`)
- Hybrid retrieval → Query embeddings: embeds query (evidence: `backend/retrieval/rag-pipeline/pipeline/retrieve.py`)
- Hybrid retrieval → Vector index: queries index (evidence: `backend/retrieval/rag-pipeline/pipeline/retrieve.py`)
- Hybrid retrieval → BM25 index: searches keywords (evidence: `backend/retrieval/rag-pipeline/pipeline/retrieve.py`)
- Grounded Q&A → Retriever adapter: retrieves context (evidence: `README.md`)
- Grounded Q&A → LLM client: generates answers (evidence: `README.md`)
- Grounded Q&A → QA prompts and citations: uses grounding rules (evidence: `backend/qa/components.py`)
- Quiz generation and grading → Retriever adapter: retrieves passages (evidence: `README.md`)
- Quiz generation and grading → LLM client: generates questions (evidence: `README.md`)
- LLM client → Ollama or hosted model: calls provider (evidence: `README.md`)
- UI actions → Orchestrator: receives results (evidence: `README.md`)
- Runtime configuration → Component contracts: selects implementations (evidence: `backend/config.py`)