# binbinao/mypodcast architecture

> Architecture diagram of the GitHub repository binbinao/mypodcast, 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/binbinao/mypodcast
- Repository: https://github.com/binbinao/mypodcast

## Overview

myPodcast turns Markdown articles into reviewed podcast scripts, then synthesizes audio and publishes RSS and a program site. The primary workflow is raw article → episode planning and script preparation → human review → read-only build → TTS audio and publication artifacts. README documents the major stages, selectable speech backends, voice selection, prosody, validation, naming rules, and resumable builds. Connections for unsampled modules are limited to documented relationships; local Qwen service internals are represented only at the documented boundary.

Main entry points: [`src/prepare.py`](https://github.com/binbinao/mypodcast/blob/main/src/prepare.py) (Prepare workflow), [`src/build.py`](https://github.com/binbinao/mypodcast/blob/main/src/build.py) (Build orchestrator), [`src/tts.py`](https://github.com/binbinao/mypodcast/blob/main/src/tts.py) (TTS backend router), [`src/backends/base.py`](https://github.com/binbinao/mypodcast/blob/main/src/backends/base.py) (Backend registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Content and review"]
  node_raw["Source articles"]
  node_drafts["Reviewed scripts"]
end

subgraph group_preparation["Script preparation"]
  node_prepare["Prepare workflow<br/>[prepare.py]"]
  node_ingest["Article ingestion<br/>[ingest.py]"]
  node_split["Episode planning<br/>[split.py]"]
  node_decisions["Format and voice decisions<br/>[decisions.py]"]
  node_generate["Script generation<br/>[generate.py]"]
  node_llm["LLM service client<br/>[llm.py]"]
  node_stages["Draft lifecycle<br/>[stages.py]"]
  node_naming["Path and slug rules<br/>[naming.py]"]
end

subgraph group_audio["Audio generation"]
  node_build["Build orchestrator<br/>[build.py]"]
  node_validate["Script validation<br/>[validate.py]"]
  node_voicecaster["Voice selection<br/>[voicecaster.py]"]
  node_prosody["Prosody planning<br/>[prosody.py]"]
  node_tts["TTS backend router<br/>[tts.py]"]
  node_backendbase["Backend registry<br/>[base.py]"]
  node_qwenlocal["Local Qwen backend<br/>[qwen3_local.py]"]
  node_cloudbackends["Cloud TTS backends"]
  node_localservice["Local Qwen service"]
end

subgraph group_publishing["Publishing"]
  node_output["Audio and manifests"]
  node_feed["RSS and site generator<br/>[feed.py]"]
end

node_author(("Article author"))
node_reviewer(("Script reviewer"))
node_listeners(("Podcast listeners"))

node_author -->|"writes"| node_raw
node_raw -->|"prepares"| node_prepare
node_prepare -->|"ingests"| node_ingest
node_prepare -->|"plans episodes"| node_split
node_prepare -->|"collects decisions"| node_decisions
node_prepare -->|"generates scripts"| node_generate
node_generate -->|"requests completion"| node_llm
node_prepare -->|"writes drafts"| node_drafts
node_reviewer -->|"edits scripts"| node_drafts
node_prepare -->|"sets review stage"| node_stages
node_prepare -->|"enforces paths"| node_naming
node_drafts -->|"builds from"| node_build
node_build -->|"checks stage"| node_stages
node_build -->|"validates scripts"| node_validate
node_build -->|"selects voice"| node_voicecaster
node_voicecaster -->|"infers voice"| node_llm
node_build -->|"synthesizes audio"| node_tts
node_tts -->|"plans prosody"| node_prosody
node_tts -->|"routes backend"| node_backendbase
node_backendbase -->|"registers"| node_qwenlocal
node_backendbase -->|"registers"| node_cloudbackends
node_qwenlocal -->|"requests speech"| node_localservice
node_build -->|"writes artifacts"| node_output
node_build -->|"refreshes publication"| node_feed
node_feed -->|"writes RSS and site"| node_output
node_output -->|"serves episodes"| node_listeners

click node_raw "https://github.com/binbinao/mypodcast/tree/main/raw"
click node_prepare "https://github.com/binbinao/mypodcast/blob/main/src/prepare.py"
click node_ingest "https://github.com/binbinao/mypodcast/blob/main/src/ingest.py"
click node_split "https://github.com/binbinao/mypodcast/blob/main/src/split.py"
click node_decisions "https://github.com/binbinao/mypodcast/blob/main/src/decisions.py"
click node_generate "https://github.com/binbinao/mypodcast/blob/main/src/generate.py"
click node_llm "https://github.com/binbinao/mypodcast/blob/main/src/llm.py"
click node_drafts "https://github.com/binbinao/mypodcast/tree/main/drafts"
click node_stages "https://github.com/binbinao/mypodcast/blob/main/src/stages.py"
click node_naming "https://github.com/binbinao/mypodcast/blob/main/src/naming.py"
click node_build "https://github.com/binbinao/mypodcast/blob/main/src/build.py"
click node_validate "https://github.com/binbinao/mypodcast/blob/main/src/validate.py"
click node_voicecaster "https://github.com/binbinao/mypodcast/blob/main/src/voicecaster.py"
click node_prosody "https://github.com/binbinao/mypodcast/blob/main/src/prosody.py"
click node_tts "https://github.com/binbinao/mypodcast/blob/main/src/tts.py"
click node_backendbase "https://github.com/binbinao/mypodcast/blob/main/src/backends/base.py"
click node_qwenlocal "https://github.com/binbinao/mypodcast/blob/main/src/backends/qwen3_local.py"
click node_cloudbackends "https://github.com/binbinao/mypodcast/tree/main/src/backends"
click node_localservice "https://github.com/binbinao/mypodcast/tree/main/scripts/qwen3-tts-local"
click node_output "https://github.com/binbinao/mypodcast/tree/main/output"
click node_feed "https://github.com/binbinao/mypodcast/blob/main/src/feed.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_raw,node_drafts,node_reviewer toneBlue
class node_prepare,node_ingest,node_split,node_decisions,node_generate,node_llm,node_stages,node_naming toneAmber
class node_build,node_validate,node_voicecaster,node_prosody,node_tts,node_backendbase,node_qwenlocal,node_cloudbackends,node_localservice toneMint
class node_output,node_feed toneRose
class node_author,node_listeners toneIndigo
```

## Components

### Content and review

- [Source articles](https://github.com/binbinao/mypodcast/tree/main/raw): `raw`
- [Reviewed scripts](https://github.com/binbinao/mypodcast/tree/main/drafts): `drafts`

### Script preparation

- [Prepare workflow](https://github.com/binbinao/mypodcast/blob/main/src/prepare.py): `src/prepare.py`
- [Article ingestion](https://github.com/binbinao/mypodcast/blob/main/src/ingest.py): `src/ingest.py`
- [Episode planning](https://github.com/binbinao/mypodcast/blob/main/src/split.py): `src/split.py`
- [Format and voice decisions](https://github.com/binbinao/mypodcast/blob/main/src/decisions.py): `src/decisions.py`
- [Script generation](https://github.com/binbinao/mypodcast/blob/main/src/generate.py): `src/generate.py`
- [LLM service client](https://github.com/binbinao/mypodcast/blob/main/src/llm.py): `src/llm.py`
- [Draft lifecycle](https://github.com/binbinao/mypodcast/blob/main/src/stages.py): `src/stages.py`
- [Path and slug rules](https://github.com/binbinao/mypodcast/blob/main/src/naming.py): `src/naming.py`

### Audio generation

- [Build orchestrator](https://github.com/binbinao/mypodcast/blob/main/src/build.py): `src/build.py`
- [Script validation](https://github.com/binbinao/mypodcast/blob/main/src/validate.py): `src/validate.py`
- [Voice selection](https://github.com/binbinao/mypodcast/blob/main/src/voicecaster.py): `src/voicecaster.py`
- [Prosody planning](https://github.com/binbinao/mypodcast/blob/main/src/prosody.py): `src/prosody.py`
- [TTS backend router](https://github.com/binbinao/mypodcast/blob/main/src/tts.py): `src/tts.py`
- [Backend registry](https://github.com/binbinao/mypodcast/blob/main/src/backends/base.py): `src/backends/base.py`
- [Local Qwen backend](https://github.com/binbinao/mypodcast/blob/main/src/backends/qwen3_local.py): `src/backends/qwen3_local.py`
- [Cloud TTS backends](https://github.com/binbinao/mypodcast/tree/main/src/backends): `src/backends`
- [Local Qwen service](https://github.com/binbinao/mypodcast/tree/main/scripts/qwen3-tts-local): `scripts/qwen3-tts-local`

### Publishing

- [Audio and manifests](https://github.com/binbinao/mypodcast/tree/main/output): `output`
- [RSS and site generator](https://github.com/binbinao/mypodcast/blob/main/src/feed.py): `src/feed.py`

### Other components

- **Article author**
- **Script reviewer**
- **Podcast listeners**

## Connections

- Article author → Source articles: writes (evidence: `README.md`)
- Source articles → Prepare workflow: prepares (evidence: `README.md`)
- Prepare workflow → Article ingestion: ingests (evidence: `README.md`)
- Prepare workflow → Episode planning: plans episodes (evidence: `README.md`)
- Prepare workflow → Format and voice decisions: collects decisions (evidence: `README.md`)
- Prepare workflow → Script generation: generates scripts (evidence: `README.md`)
- Script generation → LLM service client: requests completion (evidence: `README.md`)
- Prepare workflow → Reviewed scripts: writes drafts (evidence: `README.md`)
- Script reviewer → Reviewed scripts: edits scripts (evidence: `README.md`)
- Prepare workflow → Draft lifecycle: sets review stage (evidence: `README.md`)
- Prepare workflow → Path and slug rules: enforces paths (evidence: `README.md`)
- Reviewed scripts → Build orchestrator: builds from (evidence: `README.md`)
- Build orchestrator → Draft lifecycle: checks stage (evidence: `README.md`)
- Build orchestrator → Script validation: validates scripts (evidence: `README.md`)
- Build orchestrator → Voice selection: selects voice (evidence: `README.md`)
- Voice selection → LLM service client: infers voice (evidence: `README.md`)
- Build orchestrator → TTS backend router: synthesizes audio (evidence: `README.md`)
- TTS backend router → Prosody planning: plans prosody (evidence: `README.md`)
- TTS backend router → Backend registry: routes backend (evidence: `README.md`)
- Backend registry → Local Qwen backend: registers (evidence: `README.md`)
- Backend registry → Cloud TTS backends: registers (evidence: `README.md`)
- Local Qwen backend → Local Qwen service: requests speech (evidence: `README.md`)
- Build orchestrator → Audio and manifests: writes artifacts (evidence: `README.md`)
- Build orchestrator → RSS and site generator: refreshes publication (evidence: `README.md`)
- RSS and site generator → Audio and manifests: writes RSS and site (evidence: `README.md`)
- Audio and manifests → Podcast listeners: serves episodes (evidence: `README.md`)
