# lucasuiii/fudan_icourse_subscriber architecture

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

- Interactive diagram: https://gitdiagram.com/lucasuiii/fudan_icourse_subscriber
- Repository: https://github.com/lucasuiii/fudan_icourse_subscriber

## Overview

iCourse Subscriber monitors selected Fudan iCourse courses, processes new lecture recordings into transcripts and PPT-derived evidence, produces AI study notes, and emails them per course. The main runtime coordinates authentication, course enumeration, lecture processing, scheduling, persistence, and delivery. The README also documents the encrypted-database browser and optional ASR rescue, glossary, homework-evidence, and shared-queue capabilities. Several of those branches are represented from documentation and source-index references; unsampled implementation details are not inferred.

Main entry points: [`main.py`](https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/main.py) (Run coordinator), [`src/pipeline/lecture_runner.py`](https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/pipeline/lecture_runner.py) (Lecture processor), [`src/pipeline/ppt_pipeline.py`](https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/pipeline/ppt_pipeline.py) (PPT pipeline), [`src/ai/summarizer.py`](https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/ai/summarizer.py) (AI note generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime orchestration"]
  node_main["Run coordinator<br/>[main.py]"]
  node_rules["Session selection<br/>[session_rules.py]"]
  node_scheduler["Resource scheduler<br/>[scheduler.py]"]
  node_reporter["Run reporting<br/>[reporter.py]"]
end

subgraph group_platform["Course and media access"]
  node_webvpn["WebVPN login<br/>[webvpn.py]"]
  node_icourse["iCourse client<br/>[icourse.py]"]
end

subgraph group_intelligence["Lecture intelligence"]
  node_runner["Lecture processor<br/>[lecture_runner.py]"]
  node_ppt["PPT pipeline<br/>[ppt_pipeline.py]"]
  node_ocr["PPT OCR<br/>[ocr.py]"]
  node_dedup["Slide deduplication<br/>[ppt_dedup.py]"]
  node_transcriber["Transcript routing<br/>[transcriber.py]"]
  node_qwen["Local Qwen ASR"]
  node_quality["ASR quality review<br/>[qwen_quality.py]"]
  node_review["Bounded ASR rescue"]
  node_doubao["Cloud ASR rescue<br/>[doubao_asr.py]"]
  node_glossary["Course terminology"]
  node_homework["Homework evidence<br/>[homework_visual.py]"]
  node_summarizer["AI note generation<br/>[summarizer.py]"]
end

subgraph group_state_delivery["State and delivery"]
  node_database[("Encrypted course state<br/>[database.py]")]
  node_emailer["Course email delivery<br/>[emailer.py]"]
end

subgraph group_viewer["Encrypted course viewer"]
  node_frontend["Browser viewer<br/>[app.js]"]
  node_frontend_db["Browser database access<br/>[db.js]"]
  node_frontend_crypto["Browser decryption<br/>[crypto.js]"]
  node_frontend_github["GitHub access<br/>[github.js]"]
end

node_learner(("Subscriber"))
node_icourse_service{{"Fudan iCourse"}}
node_llm_service{{"Configured LLM provider"}}
node_doubao_service{{"Seed-ASR service"}}
node_smtp{{"SMTP service"}}
node_github[("GitHub repository")]

node_learner -->|"starts run"| node_main
node_main -->|"filters lectures"| node_rules
node_main -->|"authenticates via"| node_webvpn
node_main -->|"enumerates courses"| node_icourse
node_webvpn -->|"logs in through"| node_icourse_service
node_icourse -->|"fetches course media"| node_icourse_service
node_main -->|"processes lectures"| node_runner
node_main -->|"tracks progress"| node_database
node_main -->|"coordinates resources"| node_scheduler
node_main -->|"reports status"| node_reporter
node_main -->|"sends course notes"| node_emailer
node_runner -->|"transcribes audio"| node_transcriber
node_runner -->|"starts slide processing"| node_ppt
node_runner -->|"generates notes"| node_summarizer
node_runner -->|"saves lecture state"| node_database
node_runner -->|"schedules media work"| node_scheduler
node_runner -->|"reviews ASR evidence"| node_review
node_runner -->|"loads course terms"| node_glossary
node_runner -->|"assembles homework evidence"| node_homework
node_ppt -->|"fetches slide images"| node_icourse
node_ppt -->|"submits pages for OCR"| node_ocr
node_ppt -->|"deduplicates slides"| node_dedup
node_ppt -->|"stores page status"| node_database
node_ppt -->|"uses worker pools"| node_scheduler
node_transcriber -->|"uses local recognizer"| node_qwen
node_qwen -->|"checks recognition quality"| node_quality
node_review -->|"selects review candidates"| node_quality
node_review -->|"requests bounded rescue"| node_doubao
node_doubao -->|"recognizes selected clips"| node_doubao_service
node_summarizer -->|"requests note generation"| node_llm_service
node_summarizer -->|"uses course terms"| node_glossary
node_summarizer -->|"uses assignment evidence"| node_homework
node_emailer -->|"delivers course email"| node_smtp
node_learner -->|"browses course notes"| node_frontend
node_frontend -->|"loads database content"| node_frontend_db
node_frontend_db -->|"decrypts database"| node_frontend_crypto
node_frontend -.->|"uses repository access"| node_frontend_github
node_frontend_github -.->|"accesses repository"| node_github

click node_main "https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/main.py"
click node_rules "https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/runtime/session_rules.py"
click node_scheduler "https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/runtime/scheduler.py"
click node_reporter "https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/runtime/reporter.py"
click node_webvpn "https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/api/webvpn.py"
click node_icourse "https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/api/icourse.py"
click node_runner "https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/pipeline/lecture_runner.py"
click node_ppt "https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/pipeline/ppt_pipeline.py"
click node_ocr "https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/ai/ocr.py"
click node_dedup "https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/ai/ppt_dedup.py"
click node_transcriber "https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/ai/transcriber.py"
click node_qwen "https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/ai/qwen_transcriber.py"
click node_quality "https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/scripts/qwen_quality.py"
click node_review "https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/ai/qwen_review_ledger.py"
click node_doubao "https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/ai/doubao_asr.py"
click node_glossary "https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/ai/automatic_glossary.py"
click node_homework "https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/pipeline/homework_visual.py"
click node_summarizer "https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/ai/summarizer.py"
click node_database "https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/data/database.py"
click node_emailer "https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/api/emailer.py"
click node_frontend "https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/frontend/js/app.js"
click node_frontend_db "https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/frontend/js/db.js"
click node_frontend_crypto "https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/frontend/js/crypto.js"
click node_frontend_github "https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/frontend/js/github.js"

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_main,node_rules,node_scheduler,node_reporter toneBlue
class node_webvpn,node_icourse,node_github toneAmber
class node_runner,node_ppt,node_ocr,node_dedup,node_transcriber,node_qwen,node_quality,node_review,node_doubao,node_glossary,node_homework,node_summarizer toneMint
class node_database,node_emailer toneRose
class node_frontend,node_frontend_db,node_frontend_crypto,node_frontend_github,node_learner,node_icourse_service,node_llm_service,node_doubao_service,node_smtp toneIndigo
```

## Components

### Runtime orchestration

- [Run coordinator](https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/main.py): `main.py`
- [Session selection](https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/runtime/session_rules.py): `src/runtime/session_rules.py`
- [Resource scheduler](https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/runtime/scheduler.py): `src/runtime/scheduler.py`
- [Run reporting](https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/runtime/reporter.py): `src/runtime/reporter.py`

### Course and media access

- [WebVPN login](https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/api/webvpn.py): `src/api/webvpn.py`
- [iCourse client](https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/api/icourse.py): `src/api/icourse.py`

### Lecture intelligence

- [Lecture processor](https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/pipeline/lecture_runner.py): `src/pipeline/lecture_runner.py`
- [PPT pipeline](https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/pipeline/ppt_pipeline.py): `src/pipeline/ppt_pipeline.py`
- [PPT OCR](https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/ai/ocr.py): `src/ai/ocr.py`
- [Slide deduplication](https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/ai/ppt_dedup.py): `src/ai/ppt_dedup.py`
- [Transcript routing](https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/ai/transcriber.py): `src/ai/transcriber.py`
- [Local Qwen ASR](https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/ai/qwen_transcriber.py): `src/ai/qwen_transcriber.py`
- [ASR quality review](https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/scripts/qwen_quality.py): `scripts/qwen_quality.py`
- [Bounded ASR rescue](https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/ai/qwen_review_ledger.py): `src/ai/qwen_review_ledger.py`
- [Cloud ASR rescue](https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/ai/doubao_asr.py): `src/ai/doubao_asr.py`
- [Course terminology](https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/ai/automatic_glossary.py): `src/ai/automatic_glossary.py`
- [Homework evidence](https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/pipeline/homework_visual.py): `src/pipeline/homework_visual.py`
- [AI note generation](https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/ai/summarizer.py): `src/ai/summarizer.py`

### State and delivery

- [Encrypted course state](https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/data/database.py): `src/data/database.py`
- [Course email delivery](https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/src/api/emailer.py): `src/api/emailer.py`

### Encrypted course viewer

- [Browser viewer](https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/frontend/js/app.js): `frontend/js/app.js`
- [Browser database access](https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/frontend/js/db.js): `frontend/js/db.js`
- [Browser decryption](https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/frontend/js/crypto.js): `frontend/js/crypto.js`
- [GitHub access](https://github.com/lucasuiii/fudan_icourse_subscriber/blob/main/frontend/js/github.js): `frontend/js/github.js`

### Other components

- **Subscriber**
- **Fudan iCourse**
- **Configured LLM provider**
- **Seed-ASR service**
- **SMTP service**
- **GitHub repository**

## Connections

- Subscriber → Run coordinator: starts run (evidence: `README.md`)
- Run coordinator → Session selection: filters lectures (evidence: `main.py`)
- Run coordinator → WebVPN login: authenticates via (evidence: `main.py`)
- Run coordinator → iCourse client: enumerates courses (evidence: `main.py`)
- WebVPN login → Fudan iCourse: logs in through (evidence: `src/api/webvpn.py`)
- iCourse client → Fudan iCourse: fetches course media (evidence: `README.md`)
- Run coordinator → Lecture processor: processes lectures (evidence: `main.py`)
- Run coordinator → Encrypted course state: tracks progress (evidence: `main.py`)
- Run coordinator → Resource scheduler: coordinates resources (evidence: `main.py`)
- Run coordinator → Run reporting: reports status (evidence: `main.py`)
- Run coordinator → Course email delivery: sends course notes (evidence: `main.py`)
- Lecture processor → Transcript routing: transcribes audio (evidence: `src/pipeline/lecture_runner.py`)
- Lecture processor → PPT pipeline: starts slide processing (evidence: `src/pipeline/lecture_runner.py`)
- Lecture processor → AI note generation: generates notes (evidence: `src/pipeline/lecture_runner.py`)
- Lecture processor → Encrypted course state: saves lecture state (evidence: `src/pipeline/lecture_runner.py`)
- Lecture processor → Resource scheduler: schedules media work (evidence: `src/pipeline/lecture_runner.py`)
- Lecture processor → Bounded ASR rescue: reviews ASR evidence (evidence: `src/pipeline/lecture_runner.py`)
- Lecture processor → Course terminology: loads course terms (evidence: `src/pipeline/lecture_runner.py`)
- Lecture processor → Homework evidence: assembles homework evidence (evidence: `README.md`)
- PPT pipeline → iCourse client: fetches slide images (evidence: `src/pipeline/ppt_pipeline.py`)
- PPT pipeline → PPT OCR: submits pages for OCR (evidence: `src/pipeline/ppt_pipeline.py`)
- PPT pipeline → Slide deduplication: deduplicates slides (evidence: `src/pipeline/ppt_pipeline.py`)
- PPT pipeline → Encrypted course state: stores page status (evidence: `src/pipeline/ppt_pipeline.py`)
- PPT pipeline → Resource scheduler: uses worker pools (evidence: `src/pipeline/ppt_pipeline.py`)
- Transcript routing → Local Qwen ASR: uses local recognizer (evidence: `src/ai/transcriber.py`)
- Local Qwen ASR → ASR quality review: checks recognition quality (evidence: `src/ai/qwen_transcriber.py`)
- Bounded ASR rescue → ASR quality review: selects review candidates (evidence: `src/ai/qwen_review_ledger.py`)
- Bounded ASR rescue → Cloud ASR rescue: requests bounded rescue (evidence: `src/ai/qwen_review_ledger.py`)
- Cloud ASR rescue → Seed-ASR service: recognizes selected clips (evidence: `README.md`)
- AI note generation → Configured LLM provider: requests note generation (evidence: `README.md`)
- AI note generation → Course terminology: uses course terms (evidence: `src/ai/summarizer.py`)
- AI note generation → Homework evidence: uses assignment evidence (evidence: `src/ai/summarizer.py`)
- Course email delivery → SMTP service: delivers course email (evidence: `README.md`)
- Subscriber → Browser viewer: browses course notes (evidence: `README.md`)
- Browser viewer → Browser database access: loads database content (evidence: `README.md`)
- Browser database access → Browser decryption: decrypts database (evidence: `README.md`)
- Browser viewer → GitHub access: uses repository access
- GitHub access → GitHub repository: accesses repository
