# dleungdl/learntok architecture

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

- Interactive diagram: https://gitdiagram.com/dleungdl/learntok
- Repository: https://github.com/dleungdl/learntok

## Overview

LearnTok AI turns learning material or a script JSON into a vertical two-character educational video. The primary workflow is optional LLM script generation and quality checks, followed by Edge-TTS, optional RVC voice conversion, loudness calibration, and ffmpeg composition. Other documented branches include series planning and approval, RAG knowledge-base build/retrieval, subtitle ingestion, term migration, and environment checks. Edges follow the README workflow or explicit calls in sampled source; unsampled subsystems are represented only where their paths are in the tree and their capabilities are documented.

Main entry points: [`src/learntok/compose.py`](https://github.com/dleungdl/learntok/blob/main/src/learntok/compose.py) (Video composition), [`src/learntok/tools/script_gen.py`](https://github.com/dleungdl/learntok/blob/main/src/learntok/tools/script_gen.py) (Script generation), [`src/learntok/tools/run_pipeline.py`](https://github.com/dleungdl/learntok/blob/main/src/learntok/tools/run_pipeline.py) (Pipeline runner), [`src/learntok/tools/tts_edge.py`](https://github.com/dleungdl/learntok/blob/main/src/learntok/tools/tts_edge.py) (Edge TTS)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_content["Script authoring"]
  node_scriptgen["Script generation<br/>[script_gen.py]"]
  node_quality["Script quality gate<br/>[validate_script.py]"]
  node_scriptfix["Deterministic script fix<br/>[script_fix.py]"]
  node_srt["SRT ingestion<br/>[ingest_srt.py]"]
  node_terms["Term migration<br/>[migrate_terms.py]"]
end

subgraph group_knowledge["Knowledge and series"]
  node_series["Series planning<br/>[series_bible.py]"]
  node_ragbuild["RAG indexing<br/>[rag_build.py]"]
  node_ragstore[("ChromaDB knowledge base<br/>[rag_common.py]")]
  node_ragretrieve["RAG retrieval<br/>[rag_retrieve.py]"]
end

subgraph group_production["Audio and video"]
  node_pipeline["Pipeline runner<br/>[run_pipeline.py]"]
  node_tts["Edge TTS<br/>[tts_edge.py]"]
  node_rvc["RVC conversion<br/>[rvc_convert.py]"]
  node_calibrate["Loudness calibration<br/>[calibrate_audio.py]"]
  node_compose["Video composition<br/>[compose.py]"]
  node_video["Rendered video"]
end

subgraph group_platform["Workspace and safety"]
  node_config["Workspace configuration<br/>[config.py]"]
  node_safety["Model integrity checks<br/>[model_safety.py]"]
  node_doctor["Environment doctor<br/>[doctor.py]"]
  node_assets["Characters and media assets<br/>[manifest.json]"]
end

node_creator(("Creator"))
node_material["Learning material"]
node_llm(("LLM provider"))
node_edge_service(("Edge TTS service"))
node_ffmpeg(("ffmpeg"))
node_output["Video output"]

node_creator -->|"provides"| node_material
node_creator -.->|"requests generation"| node_scriptgen
node_material -->|"supplies source"| node_scriptgen
node_scriptgen -.->|"prompts"| node_llm
node_scriptgen -->|"validates output"| node_quality
node_quality -->|"fixes issues"| node_scriptfix
node_scriptfix -->|"rechecks"| node_quality
node_creator -->|"starts render"| node_pipeline
node_pipeline -->|"runs TTS"| node_tts
node_pipeline -->|"runs optionally"| node_rvc
node_pipeline -->|"runs calibration"| node_calibrate
node_pipeline -->|"runs composition"| node_compose
node_tts -.->|"synthesizes speech"| node_edge_service
node_tts -->|"writes timed audio"| node_compose
node_rvc -->|"verifies models"| node_safety
node_calibrate -->|"resolves workspace"| node_config
node_compose -->|"resolves tools"| node_config
node_compose -->|"reads media manifest"| node_assets
node_compose -->|"renders with"| node_ffmpeg
node_compose -->|"writes video"| node_output
node_output -->|"contains"| node_video
node_creator -->|"plans learning path"| node_series
node_series -->|"generates episodes"| node_scriptgen
node_creator -->|"builds knowledge base"| node_ragbuild
node_ragbuild -->|"upserts chunks"| node_ragstore
node_ragretrieve -->|"queries chunks"| node_ragstore
node_scriptgen -->|"retrieves context"| node_ragstore
node_creator -->|"searches facts"| node_ragretrieve
node_creator -->|"imports subtitles"| node_srt
node_creator -->|"migrates terms"| node_terms
node_doctor -->|"checks environment"| node_config
node_doctor -->|"checks models"| node_safety

click node_scriptgen "https://github.com/dleungdl/learntok/blob/main/src/learntok/tools/script_gen.py"
click node_quality "https://github.com/dleungdl/learntok/blob/main/src/learntok/tools/validate_script.py"
click node_scriptfix "https://github.com/dleungdl/learntok/blob/main/src/learntok/tools/script_fix.py"
click node_srt "https://github.com/dleungdl/learntok/blob/main/src/learntok/tools/ingest_srt.py"
click node_terms "https://github.com/dleungdl/learntok/blob/main/src/learntok/tools/migrate_terms.py"
click node_series "https://github.com/dleungdl/learntok/blob/main/src/learntok/tools/series_bible.py"
click node_ragbuild "https://github.com/dleungdl/learntok/blob/main/src/learntok/tools/rag_build.py"
click node_ragstore "https://github.com/dleungdl/learntok/blob/main/src/learntok/tools/rag_common.py"
click node_ragretrieve "https://github.com/dleungdl/learntok/blob/main/src/learntok/tools/rag_retrieve.py"
click node_pipeline "https://github.com/dleungdl/learntok/blob/main/src/learntok/tools/run_pipeline.py"
click node_tts "https://github.com/dleungdl/learntok/blob/main/src/learntok/tools/tts_edge.py"
click node_rvc "https://github.com/dleungdl/learntok/blob/main/src/learntok/tools/rvc_convert.py"
click node_calibrate "https://github.com/dleungdl/learntok/blob/main/src/learntok/tools/calibrate_audio.py"
click node_compose "https://github.com/dleungdl/learntok/blob/main/src/learntok/compose.py"
click node_config "https://github.com/dleungdl/learntok/blob/main/src/learntok/config.py"
click node_safety "https://github.com/dleungdl/learntok/blob/main/src/learntok/tools/model_safety.py"
click node_doctor "https://github.com/dleungdl/learntok/blob/main/src/learntok/doctor.py"
click node_assets "https://github.com/dleungdl/learntok/blob/main/assets/manifest.json"

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_scriptgen,node_quality,node_scriptfix,node_srt,node_terms toneBlue
class node_series,node_ragbuild,node_ragstore,node_ragretrieve toneAmber
class node_pipeline,node_tts,node_rvc,node_calibrate,node_compose,node_video toneMint
class node_config,node_safety,node_doctor,node_assets toneRose
class node_creator,node_material,node_llm,node_edge_service,node_ffmpeg,node_output toneIndigo
```

## Components

### Script authoring

- [Script generation](https://github.com/dleungdl/learntok/blob/main/src/learntok/tools/script_gen.py): `src/learntok/tools/script_gen.py`
- [Script quality gate](https://github.com/dleungdl/learntok/blob/main/src/learntok/tools/validate_script.py): `src/learntok/tools/validate_script.py`
- [Deterministic script fix](https://github.com/dleungdl/learntok/blob/main/src/learntok/tools/script_fix.py): `src/learntok/tools/script_fix.py`
- [SRT ingestion](https://github.com/dleungdl/learntok/blob/main/src/learntok/tools/ingest_srt.py): `src/learntok/tools/ingest_srt.py`
- [Term migration](https://github.com/dleungdl/learntok/blob/main/src/learntok/tools/migrate_terms.py): `src/learntok/tools/migrate_terms.py`

### Knowledge and series

- [Series planning](https://github.com/dleungdl/learntok/blob/main/src/learntok/tools/series_bible.py): `src/learntok/tools/series_bible.py`
- [RAG indexing](https://github.com/dleungdl/learntok/blob/main/src/learntok/tools/rag_build.py): `src/learntok/tools/rag_build.py`
- [ChromaDB knowledge base](https://github.com/dleungdl/learntok/blob/main/src/learntok/tools/rag_common.py): `src/learntok/tools/rag_common.py`
- [RAG retrieval](https://github.com/dleungdl/learntok/blob/main/src/learntok/tools/rag_retrieve.py): `src/learntok/tools/rag_retrieve.py`

### Audio and video

- [Pipeline runner](https://github.com/dleungdl/learntok/blob/main/src/learntok/tools/run_pipeline.py): `src/learntok/tools/run_pipeline.py`
- [Edge TTS](https://github.com/dleungdl/learntok/blob/main/src/learntok/tools/tts_edge.py): `src/learntok/tools/tts_edge.py`
- [RVC conversion](https://github.com/dleungdl/learntok/blob/main/src/learntok/tools/rvc_convert.py): `src/learntok/tools/rvc_convert.py`
- [Loudness calibration](https://github.com/dleungdl/learntok/blob/main/src/learntok/tools/calibrate_audio.py): `src/learntok/tools/calibrate_audio.py`
- [Video composition](https://github.com/dleungdl/learntok/blob/main/src/learntok/compose.py): `src/learntok/compose.py`
- **Rendered video**

### Workspace and safety

- [Workspace configuration](https://github.com/dleungdl/learntok/blob/main/src/learntok/config.py): `src/learntok/config.py`
- [Model integrity checks](https://github.com/dleungdl/learntok/blob/main/src/learntok/tools/model_safety.py): `src/learntok/tools/model_safety.py`
- [Environment doctor](https://github.com/dleungdl/learntok/blob/main/src/learntok/doctor.py): `src/learntok/doctor.py`
- [Characters and media assets](https://github.com/dleungdl/learntok/blob/main/assets/manifest.json): `assets/manifest.json`

### Other components

- **Creator**
- **Learning material**
- **LLM provider**
- **Edge TTS service**
- **ffmpeg**
- **Video output**

## Connections

- Creator → Learning material: provides (evidence: `README.md`)
- Creator → Script generation: requests generation (evidence: `README.md`)
- Learning material → Script generation: supplies source (evidence: `README.md`)
- Script generation → LLM provider: prompts (evidence: `README.md`)
- Script generation → Script quality gate: validates output (evidence: `README.md`)
- Script quality gate → Deterministic script fix: fixes issues (evidence: `src/learntok/tools/script_gen.py`)
- Deterministic script fix → Script quality gate: rechecks (evidence: `src/learntok/tools/script_fix.py`)
- Creator → Pipeline runner: starts render (evidence: `README.md`)
- Pipeline runner → Edge TTS: runs TTS (evidence: `src/learntok/tools/run_pipeline.py`)
- Pipeline runner → RVC conversion: runs optionally (evidence: `src/learntok/tools/run_pipeline.py`)
- Pipeline runner → Loudness calibration: runs calibration (evidence: `src/learntok/tools/run_pipeline.py`)
- Pipeline runner → Video composition: runs composition (evidence: `src/learntok/tools/run_pipeline.py`)
- Edge TTS → Edge TTS service: synthesizes speech (evidence: `README.md`)
- Edge TTS → Video composition: writes timed audio (evidence: `src/learntok/tools/tts_edge.py`)
- RVC conversion → Model integrity checks: verifies models (evidence: `src/learntok/tools/rvc_convert.py`)
- Loudness calibration → Workspace configuration: resolves workspace (evidence: `src/learntok/tools/calibrate_audio.py`)
- Video composition → Workspace configuration: resolves tools (evidence: `src/learntok/compose.py`)
- Video composition → Characters and media assets: reads media manifest (evidence: `README.md`)
- Video composition → ffmpeg: renders with (evidence: `README.md`)
- Video composition → Video output: writes video (evidence: `README.md`)
- Video output → Rendered video: contains (evidence: `README.md`)
- Creator → Series planning: plans learning path (evidence: `README.md`)
- Series planning → Script generation: generates episodes (evidence: `src/learntok/tools/series_bible.py`)
- Creator → RAG indexing: builds knowledge base (evidence: `README.md`)
- RAG indexing → ChromaDB knowledge base: upserts chunks (evidence: `src/learntok/tools/rag_build.py`)
- RAG retrieval → ChromaDB knowledge base: queries chunks (evidence: `src/learntok/tools/rag_retrieve.py`)
- Script generation → ChromaDB knowledge base: retrieves context (evidence: `src/learntok/tools/script_gen.py`)
- Creator → RAG retrieval: searches facts (evidence: `README.md`)
- Creator → SRT ingestion: imports subtitles (evidence: `README.md`)
- Creator → Term migration: migrates terms (evidence: `README.md`)
- Environment doctor → Workspace configuration: checks environment (evidence: `src/learntok/doctor.py`)
- Environment doctor → Model integrity checks: checks models (evidence: `src/learntok/doctor.py`)
