# khaluc/bluestudy architecture

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

- Interactive diagram: https://gitdiagram.com/khaluc/bluestudy
- Repository: https://github.com/khaluc/bluestudy
- Video tour (about a minute): https://gitdiagram.com/khaluc/bluestudy/video

## Overview

BlueStudy is an academic English learning platform. Learners upload or enter study material, review extracted text, confirm it, and create a session; the API queues study work for a worker, which dispatches classification, teaching, or study-bundle generation and persists results for later review. Separate experiences support chat and quizzes, PDF-based exams, speaking practice, and progress-based revision. The sampled sources show session processing and model routing directly; other feature connections reflect README-documented capabilities and the listed module structure, so uncertain internal call paths are omitted.

Main entry points: [`apps/api/main.py`](https://github.com/khaluc/bluestudy/blob/main/apps/api/main.py) (FastAPI application), [`packages/db/database.py`](https://github.com/khaluc/bluestudy/blob/main/packages/db/database.py) (Relational database), [`apps/worker/main.py`](https://github.com/khaluc/bluestudy/blob/main/apps/worker/main.py) (Task worker), [`apps/api/routers/speaking.py`](https://github.com/khaluc/bluestudy/blob/main/apps/api/routers/speaking.py) (Speaking workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Learner interface"]
  node_web["Web application<br/>[app.js]"]
  node_chat_ui["Chat interface<br/>[chat.js]"]
  node_exam_ui["Exam interface<br/>[exams.js]"]
  node_speaking_ui["Speaking interface<br/>[speaking.js]"]
  node_map_ui["Learning map<br/>[learning-map.js]"]
end

subgraph group_api["API and domain"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_documents["Document review<br/>[documents.py]"]
  node_uploads["Upload endpoint<br/>[uploads.py]"]
  node_sessions["Study sessions<br/>[sessions.py]"]
  node_materials["Study materials<br/>[materials.py]"]
  node_chat_api["Chat endpoint<br/>[chat.py]"]
  node_exams["Exam workflow<br/>[exams.py]"]
  node_speaking["Speaking workflow<br/>[speaking.py]"]
  node_learning_map["Progress and review<br/>[learning_map.py]"]
end

subgraph group_processing["Async processing"]
  node_worker["Task worker<br/>[main.py]"]
  node_ocr_task["OCR processing<br/>[ocr_task.py]"]
  node_study_agents["Study dispatch<br/>[orchestrator.py]"]
  node_chat_task["Chat processing<br/>[chat_task.py]"]
  node_exam_task["Exam processing<br/>[exam_task.py]"]
  node_speaking_task["Speaking processing<br/>[speaking_task.py]"]
  node_ocr["OCR pipeline<br/>[process.py]"]
end

subgraph group_state["State and files"]
  node_database[("Relational database<br/>[database.py]")]
  node_storage["Local file storage<br/>[local.py]"]
end

subgraph group_models["AI and integrations"]
  node_chat_service["Chat service<br/>[main.py]"]
  node_model_router["Model routing<br/>[qwen_client.py]"]
  node_local_model["Ollama model<br/>[gemma_client.py]"]
end

node_learner(("Learner"))
node_cloud_model{{"Qwen cloud"}}
node_assemblyai{{"AssemblyAI transcription"}}

node_learner -->|"uses"| node_web
node_web -->|"requests"| node_api_app
node_chat_ui -->|"sends chat"| node_chat_api
node_exam_ui -->|"requests exams"| node_exams
node_speaking_ui -->|"requests practice"| node_speaking
node_map_ui -->|"requests progress"| node_learning_map
node_api_app -->|"routes uploads"| node_uploads
node_api_app -->|"routes documents"| node_documents
node_api_app -->|"routes sessions"| node_sessions
node_api_app -->|"routes materials"| node_materials
node_api_app -->|"routes chat"| node_chat_api
node_api_app -->|"routes exams"| node_exams
node_api_app -->|"routes speaking"| node_speaking
node_api_app -->|"routes progress"| node_learning_map
node_uploads -->|"records uploads"| node_database
node_uploads -->|"stores source files"| node_storage
node_worker -->|"runs upload task"| node_ocr_task
node_ocr_task -->|"extracts text"| node_ocr
node_ocr_task -->|"reads source"| node_storage
node_sessions -->|"reads and writes"| node_database
node_sessions -->|"queues jobs"| node_worker
node_worker -->|"dispatches study work"| node_study_agents
node_study_agents -->|"persists results"| node_database
node_study_agents -->|"requests generation"| node_chat_service
node_worker -->|"runs chat task"| node_chat_task
node_worker -->|"runs exam tasks"| node_exam_task
node_worker -->|"runs speaking task"| node_speaking_task
node_chat_api -->|"requests response"| node_chat_service
node_chat_service -->|"routes completion"| node_model_router
node_model_router -->|"uses local model"| node_local_model
node_model_router -.->|"uses cloud model"| node_cloud_model
node_exams -->|"stores attempts"| node_database
node_speaking -->|"stores practice"| node_database
node_speaking -.->|"transcribes audio"| node_assemblyai
node_learning_map -->|"reads progress"| node_database
node_documents -->|"reads and writes"| node_database
node_materials -->|"reads and writes"| node_database

click node_web "https://github.com/khaluc/bluestudy/blob/main/apps/web/app.js"
click node_chat_ui "https://github.com/khaluc/bluestudy/blob/main/apps/web/chat.js"
click node_exam_ui "https://github.com/khaluc/bluestudy/blob/main/apps/web/exams.js"
click node_speaking_ui "https://github.com/khaluc/bluestudy/blob/main/apps/web/speaking.js"
click node_map_ui "https://github.com/khaluc/bluestudy/blob/main/apps/web/learning-map.js"
click node_api_app "https://github.com/khaluc/bluestudy/blob/main/apps/api/main.py"
click node_documents "https://github.com/khaluc/bluestudy/blob/main/apps/api/routers/documents.py"
click node_uploads "https://github.com/khaluc/bluestudy/blob/main/apps/api/routers/uploads.py"
click node_sessions "https://github.com/khaluc/bluestudy/blob/main/apps/api/routers/sessions.py"
click node_materials "https://github.com/khaluc/bluestudy/blob/main/apps/api/routers/materials.py"
click node_chat_api "https://github.com/khaluc/bluestudy/blob/main/apps/api/routers/chat.py"
click node_exams "https://github.com/khaluc/bluestudy/blob/main/apps/api/routers/exams.py"
click node_speaking "https://github.com/khaluc/bluestudy/blob/main/apps/api/routers/speaking.py"
click node_learning_map "https://github.com/khaluc/bluestudy/blob/main/apps/api/routers/learning_map.py"
click node_worker "https://github.com/khaluc/bluestudy/blob/main/apps/worker/main.py"
click node_ocr_task "https://github.com/khaluc/bluestudy/blob/main/apps/worker/tasks/ocr_task.py"
click node_study_agents "https://github.com/khaluc/bluestudy/blob/main/apps/chat/agents/orchestrator.py"
click node_chat_task "https://github.com/khaluc/bluestudy/blob/main/apps/worker/tasks/chat_task.py"
click node_exam_task "https://github.com/khaluc/bluestudy/blob/main/apps/worker/tasks/exam_task.py"
click node_speaking_task "https://github.com/khaluc/bluestudy/blob/main/apps/worker/tasks/speaking_task.py"
click node_database "https://github.com/khaluc/bluestudy/blob/main/packages/db/database.py"
click node_storage "https://github.com/khaluc/bluestudy/blob/main/packages/storage/local.py"
click node_ocr "https://github.com/khaluc/bluestudy/blob/main/packages/ocr/process.py"
click node_chat_service "https://github.com/khaluc/bluestudy/blob/main/apps/chat/main.py"
click node_model_router "https://github.com/khaluc/bluestudy/blob/main/packages/llm/qwen_client.py"
click node_local_model "https://github.com/khaluc/bluestudy/blob/main/packages/llm/gemma_client.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_chat_ui,node_exam_ui,node_speaking_ui,node_map_ui toneBlue
class node_api_app,node_documents,node_uploads,node_sessions,node_materials,node_chat_api,node_exams,node_speaking,node_learning_map toneAmber
class node_worker,node_ocr_task,node_study_agents,node_chat_task,node_exam_task,node_speaking_task,node_ocr toneMint
class node_database,node_storage toneRose
class node_chat_service,node_model_router,node_local_model,node_learner,node_cloud_model,node_assemblyai toneIndigo
```

## Components

### Learner interface

- [Web application](https://github.com/khaluc/bluestudy/blob/main/apps/web/app.js): `apps/web/app.js`
- [Chat interface](https://github.com/khaluc/bluestudy/blob/main/apps/web/chat.js): `apps/web/chat.js`
- [Exam interface](https://github.com/khaluc/bluestudy/blob/main/apps/web/exams.js): `apps/web/exams.js`
- [Speaking interface](https://github.com/khaluc/bluestudy/blob/main/apps/web/speaking.js): `apps/web/speaking.js`
- [Learning map](https://github.com/khaluc/bluestudy/blob/main/apps/web/learning-map.js): `apps/web/learning-map.js`

### API and domain

- [FastAPI application](https://github.com/khaluc/bluestudy/blob/main/apps/api/main.py): `apps/api/main.py`
- [Document review](https://github.com/khaluc/bluestudy/blob/main/apps/api/routers/documents.py): `apps/api/routers/documents.py`
- [Upload endpoint](https://github.com/khaluc/bluestudy/blob/main/apps/api/routers/uploads.py): `apps/api/routers/uploads.py`
- [Study sessions](https://github.com/khaluc/bluestudy/blob/main/apps/api/routers/sessions.py): `apps/api/routers/sessions.py`
- [Study materials](https://github.com/khaluc/bluestudy/blob/main/apps/api/routers/materials.py): `apps/api/routers/materials.py`
- [Chat endpoint](https://github.com/khaluc/bluestudy/blob/main/apps/api/routers/chat.py): `apps/api/routers/chat.py`
- [Exam workflow](https://github.com/khaluc/bluestudy/blob/main/apps/api/routers/exams.py): `apps/api/routers/exams.py`
- [Speaking workflow](https://github.com/khaluc/bluestudy/blob/main/apps/api/routers/speaking.py): `apps/api/routers/speaking.py`
- [Progress and review](https://github.com/khaluc/bluestudy/blob/main/apps/api/routers/learning_map.py): `apps/api/routers/learning_map.py`

### Async processing

- [Task worker](https://github.com/khaluc/bluestudy/blob/main/apps/worker/main.py): `apps/worker/main.py`
- [OCR processing](https://github.com/khaluc/bluestudy/blob/main/apps/worker/tasks/ocr_task.py): `apps/worker/tasks/ocr_task.py`
- [Study dispatch](https://github.com/khaluc/bluestudy/blob/main/apps/chat/agents/orchestrator.py): `apps/chat/agents/orchestrator.py`
- [Chat processing](https://github.com/khaluc/bluestudy/blob/main/apps/worker/tasks/chat_task.py): `apps/worker/tasks/chat_task.py`
- [Exam processing](https://github.com/khaluc/bluestudy/blob/main/apps/worker/tasks/exam_task.py): `apps/worker/tasks/exam_task.py`
- [Speaking processing](https://github.com/khaluc/bluestudy/blob/main/apps/worker/tasks/speaking_task.py): `apps/worker/tasks/speaking_task.py`
- [OCR pipeline](https://github.com/khaluc/bluestudy/blob/main/packages/ocr/process.py): `packages/ocr/process.py`

### State and files

- [Relational database](https://github.com/khaluc/bluestudy/blob/main/packages/db/database.py): `packages/db/database.py`
- [Local file storage](https://github.com/khaluc/bluestudy/blob/main/packages/storage/local.py): `packages/storage/local.py`

### AI and integrations

- [Chat service](https://github.com/khaluc/bluestudy/blob/main/apps/chat/main.py): `apps/chat/main.py`
- [Model routing](https://github.com/khaluc/bluestudy/blob/main/packages/llm/qwen_client.py): `packages/llm/qwen_client.py`
- [Ollama model](https://github.com/khaluc/bluestudy/blob/main/packages/llm/gemma_client.py): `packages/llm/gemma_client.py`

### Other components

- **Learner**
- **Qwen cloud**
- **AssemblyAI transcription**

## Connections

- Learner → Web application: uses
- Web application → FastAPI application: requests
- Chat interface → Chat endpoint: sends chat
- Exam interface → Exam workflow: requests exams
- Speaking interface → Speaking workflow: requests practice
- Learning map → Progress and review: requests progress
- FastAPI application → Upload endpoint: routes uploads
- FastAPI application → Document review: routes documents
- FastAPI application → Study sessions: routes sessions
- FastAPI application → Study materials: routes materials
- FastAPI application → Chat endpoint: routes chat
- FastAPI application → Exam workflow: routes exams
- FastAPI application → Speaking workflow: routes speaking
- FastAPI application → Progress and review: routes progress
- Upload endpoint → Relational database: records uploads
- Upload endpoint → Local file storage: stores source files
- Task worker → OCR processing: runs upload task
- OCR processing → OCR pipeline: extracts text
- OCR processing → Local file storage: reads source
- Study sessions → Relational database: reads and writes
- Study sessions → Task worker: queues jobs
- Task worker → Study dispatch: dispatches study work
- Study dispatch → Relational database: persists results
- Study dispatch → Chat service: requests generation
- Task worker → Chat processing: runs chat task
- Task worker → Exam processing: runs exam tasks
- Task worker → Speaking processing: runs speaking task
- Chat endpoint → Chat service: requests response
- Chat service → Model routing: routes completion
- Model routing → Ollama model: uses local model
- Model routing → Qwen cloud: uses cloud model
- Exam workflow → Relational database: stores attempts
- Speaking workflow → Relational database: stores practice
- Speaking workflow → AssemblyAI transcription: transcribes audio
- Progress and review → Relational database: reads progress
- Document review → Relational database: reads and writes
- Study materials → Relational database: reads and writes