# nicglazkov/chalkboard architecture

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

- Interactive diagram: https://gitdiagram.com/nicglazkov/chalkboard
- Repository: https://github.com/nicglazkov/chalkboard

## Overview

1. **What the system is**
   - Chalkboard is a Python CLI that turns a topic plus optional source material into a narrated Manim video.
   - The core output path is: topic/context → scripted explainer → fact validation → Manim scene code → code validation → TTS audio → Docker render → merged `final.mp4`.

2. **Entry point and configuration boundary**
   - `main.py` is the CLI entry point.
   - `config.py` centralizes environment-driven settings such as model/API keys, default audience/tone/theme/effort, output directory, checkpoint DB path, and TTS backend selection.
   - This keeps runtime configuration separate from the pipeline logic and allows the same pipeline to run in interactive, resumed, or scripted modes.

3. **Pipeline orchestration layer**
   - `pipeline/graph.py` defines the LangGraph state machine that coordinates the whole run.
   - `pipeline/state.py` holds the shared pipeline state and validation result types passed between stages.
   - `pipeline/agents/orchestrator.py` manages stage transitions, retries, and when the system should ask for user guidance after repeated failures.

4. **Content generation and validation stages**
   - `pipeline/agents/script_agent.py` creates the educational narration script.
   - `pipeline/agents/fact_validator.py` checks the script’s claims for correctness.
   - `pipeline/agents/manim_agent.py` turns the approved script into Manim animation code.
   - `pipeline/agents/code_validator.py` checks the generated code before rendering.
   - These are distinct agent boundaries: one produces content, the next approves or rejects it, and the next stage depends on that approval.

5. **External model dependency**
   - The repository is built around Claude/Anthropic for the agentic text-generation and validation steps.
   - The README’s “automatic retry logic” and “ask you for guidance” behavior imply the pipeline is resilient to model failure, but still human-in-the-loop when it can’t converge.

6. **Context ingestion subsystem**
   - `pipeline/context.py` collects and normalizes external source material from local files, directories, URLs, and GitHub README content.
   - This context is injected before generation so the script can be grounded in existing material, not just the topic prompt.
   - The README notes that context is not stored in checkpoints, so it must be re-supplied when resuming a run.

7. **Rendering boundary**
   - `pipeline/render_trigger.py` is the bridge from “AI pipeline output” to “actual video artifact.”
   - It writes output files for rendering, invokes TTS, and coordinates the Docker/ffmpeg-based render/merge flow.
   - This is an important system boundary: the AI pipeline is pure-ish Python state, while rendering is an isolated media build step.

8. **Dockerized Manim execution**
   - `docker/Dockerfile` builds on `manimcommunity/manim:v0.20.1`.
   - `docker/render.sh` runs the scene render inside the container.
   - Docker is used to isolate Manim and ffmpeg rendering dependencies from the host environment, which matters for reproducibility and for the preview/full-render workflow.

9. **Text-to-speech subsystem**
   - `pipeline/tts/base.py` defines the TTS abstraction.
   - `pipeline/tts/openai_tts.py`, `pipeline/tts/elevenlabs_tts.py`, and `pipeline/tts/kokoro_tts.py` are interchangeable backends.
   - The backend choice is an architectural seam: cloud APIs (`openai`, `elevenlabs`) versus local inference (`kokoro`), with speed adjustment handled per backend or via post-processing.

10. **Retries, timeouts, and recovery**
   - `pipeline/retry.py` contains retry/time-limit logic used by the agents and render flow.
   - The system supports resumable runs via `--run-id`, with checkpoints stored in `pipeline_state.db`.
   - This means the pipeline is designed as a long-running, failure-tolerant workflow rather than a single-shot command.

11. **Visual QA feedback loop**
   - `pipeline/visual_qa.py` samples frames from the rendered video and asks Claude to detect visual defects like overlap, off-screen text, or readability problems.
   - If QA finds issues, Chalkboard can regenerate the Manim scene and re-render, up to a small number of attempts.
   - This makes the render stage self-correcting and closes the loop between generated code and visual output.

12. **Output artifacts and post-processing**
   - Outputs live under `output/<run-id>/`.
   - Key artifacts include the rendered video, `captions.srt`, chapter markers embedded into the MP4, and optional `quiz.json`.
   - Features like `--preview`, `--burn-captions`, `--quiz`, and `--no-render` are not separate systems; they are different paths through the same pipeline and output boundary.

13. **Test and documentation structure**
   - `tests/` mirrors the main modules, with focused tests for agents, retries, context loading, TTS backends, rendering, and visual QA.
   - `docs/` contains planning/spec documents for major pipeline changes, which suggests the architecture evolved through staged design work and has clear subsystem ownership.

14. **How to draw the architecture**
   - A good diagram would show four layers: CLI/config, LangGraph agent pipeline, render/TTS infrastructure, and output artifacts.
   - The central flows are: topic/context into script generation, script into validation and Manim generation, approved scene code into Docker render, audio into merge, and rendered frames back into visual QA with a possible regeneration loop.

Main entry points: [`pipeline/render_trigger.py`](https://github.com/nicglazkov/chalkboard/blob/main/pipeline/render_trigger.py) (Render Trigger), [`pipeline/agents/orchestrator.py`](https://github.com/nicglazkov/chalkboard/blob/main/pipeline/agents/orchestrator.py) (Orchestrator), [`pipeline/tts/base.py`](https://github.com/nicglazkov/chalkboard/blob/main/pipeline/tts/base.py) (TTS API), [`pipeline/visual_qa.py`](https://github.com/nicglazkov/chalkboard/blob/main/pipeline/visual_qa.py) (Visual QA)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_cli["CLI & Config"]
  node_main_py["CLI<br/>entrypoint<br/>[main.py]"]
  node_config_py["Config<br/>settings<br/>[config.py]"]
end

subgraph group_group_pipeline["Pipeline Core"]
  node_pipeline_graph_py{{"Graph<br/>[graph.py]"}}
  node_pipeline_state_py["State<br/>[state.py]"]
  node_orchestrator_py["Orchestrator<br/>control-loop<br/>[orchestrator.py]"]
  node_retry_py["Retries<br/>recovery<br/>[retry.py]"]
end

subgraph group_group_content["Content Pipeline"]
  node_context_py["Context<br/>ingestion<br/>[context.py]"]
  node_script_agent_py["Script<br/>agent<br/>[script_agent.py]"]
  node_fact_validator_py["Fact Check<br/>validator<br/>[fact_validator.py]"]
  node_manim_agent_py["Manim Code<br/>agent<br/>[manim_agent.py]"]
  node_code_validator_py["Code Check<br/>validator<br/>[code_validator.py]"]
end

subgraph group_group_render["Render & QA"]
  node_render_trigger_py["Render Trigger<br/>bridge<br/>[render_trigger.py]"]
  node_visual_qa_py["Visual QA<br/>qa-loop<br/>[visual_qa.py]"]
  node_tts_base_py["TTS API<br/>abstraction<br/>[base.py]"]
  node_openai_tts_py["OpenAI TTS<br/>backend<br/>[openai_tts.py]"]
  node_elevenlabs_tts_py["ElevenLabs TTS<br/>backend<br/>[elevenlabs_tts.py]"]
  node_kokoro_tts_py["Kokoro TTS<br/>backend<br/>[kokoro_tts.py]"]
  node_dockerfile["Docker image<br/>container-build"]
  node_render_sh["Render script<br/>container-runner<br/>[render.sh]"]
end

subgraph group_group_outputs["Artifacts"]
  node_output_dir[("Run output<br/>artifacts")]
end

node_main_py -->|"loads"| node_config_py
node_main_py -->|"starts"| node_pipeline_graph_py
node_pipeline_graph_py -->|"drives"| node_orchestrator_py
node_orchestrator_py -->|"updates"| node_pipeline_state_py
node_orchestrator_py -->|"uses"| node_retry_py
node_orchestrator_py -->|"ingests"| node_context_py
node_context_py -->|"feeds"| node_script_agent_py
node_script_agent_py -->|"checks"| node_fact_validator_py
node_fact_validator_py -->|"approves"| node_manim_agent_py
node_manim_agent_py -->|"checks"| node_code_validator_py
node_code_validator_py -->|"releases"| node_render_trigger_py
node_render_trigger_py -->|"invokes"| node_tts_base_py
node_tts_base_py -->|"implements"| node_openai_tts_py
node_tts_base_py -->|"implements"| node_elevenlabs_tts_py
node_tts_base_py -->|"implements"| node_kokoro_tts_py
node_render_trigger_py -->|"builds"| node_dockerfile
node_render_trigger_py -->|"runs"| node_render_sh
node_render_trigger_py -->|"writes"| node_output_dir
node_render_trigger_py -->|"samples"| node_visual_qa_py
node_visual_qa_py -->|"regenerates"| node_manim_agent_py
node_visual_qa_py -->|"rerenders"| node_render_trigger_py
node_retry_py -->|"guards"| node_orchestrator_py

click node_main_py "https://github.com/nicglazkov/chalkboard/blob/main/main.py"
click node_config_py "https://github.com/nicglazkov/chalkboard/blob/main/config.py"
click node_pipeline_graph_py "https://github.com/nicglazkov/chalkboard/blob/main/pipeline/graph.py"
click node_pipeline_state_py "https://github.com/nicglazkov/chalkboard/blob/main/pipeline/state.py"
click node_orchestrator_py "https://github.com/nicglazkov/chalkboard/blob/main/pipeline/agents/orchestrator.py"
click node_retry_py "https://github.com/nicglazkov/chalkboard/blob/main/pipeline/retry.py"
click node_context_py "https://github.com/nicglazkov/chalkboard/blob/main/pipeline/context.py"
click node_script_agent_py "https://github.com/nicglazkov/chalkboard/blob/main/pipeline/agents/script_agent.py"
click node_fact_validator_py "https://github.com/nicglazkov/chalkboard/blob/main/pipeline/agents/fact_validator.py"
click node_manim_agent_py "https://github.com/nicglazkov/chalkboard/blob/main/pipeline/agents/manim_agent.py"
click node_code_validator_py "https://github.com/nicglazkov/chalkboard/blob/main/pipeline/agents/code_validator.py"
click node_render_trigger_py "https://github.com/nicglazkov/chalkboard/blob/main/pipeline/render_trigger.py"
click node_visual_qa_py "https://github.com/nicglazkov/chalkboard/blob/main/pipeline/visual_qa.py"
click node_tts_base_py "https://github.com/nicglazkov/chalkboard/blob/main/pipeline/tts/base.py"
click node_openai_tts_py "https://github.com/nicglazkov/chalkboard/blob/main/pipeline/tts/openai_tts.py"
click node_elevenlabs_tts_py "https://github.com/nicglazkov/chalkboard/blob/main/pipeline/tts/elevenlabs_tts.py"
click node_kokoro_tts_py "https://github.com/nicglazkov/chalkboard/blob/main/pipeline/tts/kokoro_tts.py"
click node_dockerfile "https://github.com/nicglazkov/chalkboard/tree/main/docker/Dockerfile"
click node_render_sh "https://github.com/nicglazkov/chalkboard/blob/main/docker/render.sh"
click node_output_dir "https://github.com/nicglazkov/chalkboard/tree/main/output"

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_py,node_config_py toneBlue
class node_pipeline_graph_py,node_pipeline_state_py,node_orchestrator_py,node_retry_py toneAmber
class node_context_py,node_script_agent_py,node_fact_validator_py,node_manim_agent_py,node_code_validator_py toneMint
class node_render_trigger_py,node_visual_qa_py,node_tts_base_py,node_openai_tts_py,node_elevenlabs_tts_py,node_kokoro_tts_py,node_dockerfile,node_render_sh toneRose
class node_output_dir toneIndigo
```

## Components

### CLI & Config

Entry point and runtime settings boundary.

- [CLI](https://github.com/nicglazkov/chalkboard/blob/main/main.py): entrypoint · Command-line entry point for running Chalkboard. · `main.py`
- [Config](https://github.com/nicglazkov/chalkboard/blob/main/config.py): settings · Environment-driven settings for models, defaults, output, checkpoints, and TTS backend. · `config.py`

### Pipeline Core

LangGraph state machine, shared state, and orchestration.

- [Graph](https://github.com/nicglazkov/chalkboard/blob/main/pipeline/graph.py): langgraph · Defines the pipeline state machine and stage wiring. · `pipeline/graph.py`
- [State](https://github.com/nicglazkov/chalkboard/blob/main/pipeline/state.py): shared-state · Pipeline state and validation result types passed between stages. · `pipeline/state.py`
- [Orchestrator](https://github.com/nicglazkov/chalkboard/blob/main/pipeline/agents/orchestrator.py): control-loop · Manages stage transitions, retries, and human guidance prompts. · `pipeline/agents/orchestrator.py`
- [Retries](https://github.com/nicglazkov/chalkboard/blob/main/pipeline/retry.py): recovery · Timeout and retry utilities shared by agents and render flow. · `pipeline/retry.py`

### Content Pipeline

Topic ingestion, script generation, and validation stages.

- [Context](https://github.com/nicglazkov/chalkboard/blob/main/pipeline/context.py): ingestion · Loads and normalizes source material from files, URLs, directories, and GitHub README content. · `pipeline/context.py`
- [Script](https://github.com/nicglazkov/chalkboard/blob/main/pipeline/agents/script_agent.py): agent · Creates the educational narration script from topic and context. · `pipeline/agents/script_agent.py`
- [Fact Check](https://github.com/nicglazkov/chalkboard/blob/main/pipeline/agents/fact_validator.py): validator · Checks script claims for correctness. · `pipeline/agents/fact_validator.py`
- [Manim Code](https://github.com/nicglazkov/chalkboard/blob/main/pipeline/agents/manim_agent.py): agent · Turns the approved script into Manim animation code. · `pipeline/agents/manim_agent.py`
- [Code Check](https://github.com/nicglazkov/chalkboard/blob/main/pipeline/agents/code_validator.py): validator · Validates generated Manim code before rendering. · `pipeline/agents/code_validator.py`

### Render & QA

TTS, Docker rendering, and visual feedback loop.

- [Render Trigger](https://github.com/nicglazkov/chalkboard/blob/main/pipeline/render_trigger.py): bridge · Coordinates TTS, scene writing, Docker render, and media merge. · `pipeline/render_trigger.py`
- [Visual QA](https://github.com/nicglazkov/chalkboard/blob/main/pipeline/visual_qa.py): qa-loop · Samples rendered frames and checks for visual defects. · `pipeline/visual_qa.py`
- [TTS API](https://github.com/nicglazkov/chalkboard/blob/main/pipeline/tts/base.py): abstraction · Common interface for text-to-speech backends. · `pipeline/tts/base.py`
- [OpenAI TTS](https://github.com/nicglazkov/chalkboard/blob/main/pipeline/tts/openai_tts.py): backend · Cloud text-to-speech backend. · `pipeline/tts/openai_tts.py`
- [ElevenLabs TTS](https://github.com/nicglazkov/chalkboard/blob/main/pipeline/tts/elevenlabs_tts.py): backend · Cloud text-to-speech backend. · `pipeline/tts/elevenlabs_tts.py`
- [Kokoro TTS](https://github.com/nicglazkov/chalkboard/blob/main/pipeline/tts/kokoro_tts.py): backend · Local text-to-speech backend. · `pipeline/tts/kokoro_tts.py`
- [Docker image](https://github.com/nicglazkov/chalkboard/tree/main/docker/Dockerfile): container-build · Manim/ffmpeg container image for isolated rendering. · `docker/Dockerfile`
- [Render script](https://github.com/nicglazkov/chalkboard/blob/main/docker/render.sh): container-runner · Container entry script for rendering the scene. · `docker/render.sh`

### Artifacts

Primary output files and run directory.

- [Run output](https://github.com/nicglazkov/chalkboard/tree/main/output): artifacts · Per-run output directory containing rendered media and sidecar files. · `output`

## Connections

- CLI → Config: loads · CLI reads runtime configuration.
- CLI → Graph: starts · CLI invokes the pipeline graph.
- Graph → Orchestrator: drives · Graph delegates control to the orchestrator.
- Orchestrator → State: updates · Stages share and mutate pipeline state.
- Orchestrator → Retries: uses · Retry and timeout logic protects stage execution.
- Orchestrator → Context: ingests · Context is collected before generation.
- Context → Script: feeds · Normalized source material grounds script generation.
- Script → Fact Check: checks · Generated narration is validated for factual correctness.
- Fact Check → Manim Code: approves · Validated script advances to animation code generation.
- Manim Code → Code Check: checks · Generated Manim code is validated before render.
- Code Check → Render Trigger: releases · Approved code enters the render boundary.
- Render Trigger → TTS API: invokes · Render flow requests narration audio through the TTS abstraction.
- TTS API → OpenAI TTS: implements · One selectable TTS backend.
- TTS API → ElevenLabs TTS: implements · One selectable TTS backend.
- TTS API → Kokoro TTS: implements · One selectable TTS backend.
- Render Trigger → Docker image: builds · Manim rendering runs in an isolated container image.
- Render Trigger → Render script: runs · Containerized render script executes the scene build.
- Render Trigger → Run output: writes · Rendered media and sidecar files are emitted per run.
- Render Trigger → Visual QA: samples · Rendered output is inspected for visual defects.
- Visual QA → Manim Code: regenerates · QA failures can trigger a new scene generation pass.
- Visual QA → Render Trigger: rerenders · QA failures can trigger another render attempt.
- Retries → Orchestrator: guards · Failures can route control back through retries and recovery.
