# thiet1910-bam/2d-illustrated-history architecture

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

- Interactive diagram: https://gitdiagram.com/thiet1910-bam/2d-illustrated-history
- Repository: https://github.com/thiet1910-bam/2d-illustrated-history

## Overview

Ziro-History-Studio-v3 is a toolkit for producing long-form illustrated history videos. Episode materials are organized into adaptive clusters with narration timing and lip-sync data; audio is mixed, scenes are rendered to video, outputs can be visually checked, and cluster videos can be concatenated into a master. The repository also provides reusable character, typography, and map drawing tools plus Wikimedia image discovery. Several engine connections are documented in the README, but unsampled renderer and episode wiring is not inferred here.

Main entry points: [`shared/ziro_kit/helpers.js`](https://github.com/thiet1910-bam/2d-illustrated-history/blob/main/shared/ziro_kit/helpers.js) (Drawing Helpers), [`engine/mix_audio.py`](https://github.com/thiet1910-bam/2d-illustrated-history/blob/main/engine/mix_audio.py) (Audio Mixer), [`episodes`](https://github.com/thiet1910-bam/2d-illustrated-history/tree/main/episodes) (Cluster Videos), [`shared/ziro_kit/maps.js`](https://github.com/thiet1910-bam/2d-illustrated-history/blob/main/shared/ziro_kit/maps.js) (Map Drawing Tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_episode["Episode Production"]
  node_episode_materials["Episode Materials"]
  node_cluster_scanner["Cluster Scanner<br/>[scan_clusters.py]"]
  node_wikimedia["Wikimedia Image Finder<br/>[fetch_wikimedia.py]"]
end

subgraph group_media["Media Processing"]
  node_audio_mixer["Audio Mixer<br/>[mix_audio.py]"]
  node_audio_assets["BGM and SFX"]
  node_video_renderer["Canvas Video Renderer<br/>[render.js]"]
end

subgraph group_visual["Visual Toolkit"]
  node_brand_host["Brand Host<br/>[brand_host.js]"]
  node_skit_rig["Skit Character Rig<br/>[skit_rig.js]"]
  node_kinetic_type["Kinetic Typography<br/>[kinetic_type.js]"]
  node_map_tools["Map Drawing Tools<br/>[maps.js]"]
  node_visual_helpers["Drawing Helpers<br/>[helpers.js]"]
  node_map_assets["Satellite Map"]
end

subgraph group_delivery["Review and Delivery"]
  node_qa_sheet["Visual QA Sheet<br/>[build_qa_sheet.py]"]
  node_cluster_videos["Cluster Videos"]
  node_master_concat["Master Concatenator<br/>[concat_master.py]"]
  node_master_video["Master Video"]
end

node_creator(("Episode Creator"))

node_creator -->|"creates"| node_episode_materials
node_episode_materials -->|"provides episode"| node_cluster_scanner
node_cluster_scanner -.->|"prepares cluster audio"| node_audio_mixer
node_audio_mixer -->|"uses audio"| node_audio_assets
node_audio_mixer -.->|"mixes for rendering"| node_video_renderer
node_wikimedia -.->|"complements maps"| node_map_assets
node_map_tools -->|"draws from"| node_map_assets
node_brand_host -->|"uses helpers"| node_visual_helpers
node_skit_rig -->|"uses helpers"| node_visual_helpers
node_kinetic_type -->|"uses helpers"| node_visual_helpers
node_map_tools -->|"uses helpers"| node_visual_helpers
node_video_renderer -->|"renders MP4"| node_cluster_videos
node_cluster_videos -->|"checks rendered output"| node_qa_sheet
node_cluster_videos -->|"provides clusters"| node_master_concat
node_master_concat -->|"concatenates"| node_master_video

click node_episode_materials "https://github.com/thiet1910-bam/2d-illustrated-history/tree/main/episodes"
click node_cluster_scanner "https://github.com/thiet1910-bam/2d-illustrated-history/blob/main/engine/scan_clusters.py"
click node_wikimedia "https://github.com/thiet1910-bam/2d-illustrated-history/blob/main/engine/fetch_wikimedia.py"
click node_audio_mixer "https://github.com/thiet1910-bam/2d-illustrated-history/blob/main/engine/mix_audio.py"
click node_audio_assets "https://github.com/thiet1910-bam/2d-illustrated-history/tree/main/shared"
click node_video_renderer "https://github.com/thiet1910-bam/2d-illustrated-history/blob/main/engine/render.js"
click node_brand_host "https://github.com/thiet1910-bam/2d-illustrated-history/blob/main/shared/ziro_kit/brand_host.js"
click node_skit_rig "https://github.com/thiet1910-bam/2d-illustrated-history/blob/main/shared/ziro_kit/skit_rig.js"
click node_kinetic_type "https://github.com/thiet1910-bam/2d-illustrated-history/blob/main/shared/ziro_kit/kinetic_type.js"
click node_map_tools "https://github.com/thiet1910-bam/2d-illustrated-history/blob/main/shared/ziro_kit/maps.js"
click node_visual_helpers "https://github.com/thiet1910-bam/2d-illustrated-history/blob/main/shared/ziro_kit/helpers.js"
click node_map_assets "https://github.com/thiet1910-bam/2d-illustrated-history/tree/main/shared/maps"
click node_qa_sheet "https://github.com/thiet1910-bam/2d-illustrated-history/blob/main/engine/build_qa_sheet.py"
click node_cluster_videos "https://github.com/thiet1910-bam/2d-illustrated-history/tree/main/episodes"
click node_master_concat "https://github.com/thiet1910-bam/2d-illustrated-history/blob/main/engine/concat_master.py"
click node_master_video "https://github.com/thiet1910-bam/2d-illustrated-history/tree/main/episodes"

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_episode_materials,node_cluster_scanner,node_wikimedia toneBlue
class node_audio_mixer,node_audio_assets,node_video_renderer toneAmber
class node_brand_host,node_skit_rig,node_kinetic_type,node_map_tools,node_visual_helpers,node_map_assets toneMint
class node_qa_sheet,node_cluster_videos,node_master_concat,node_master_video toneRose
class node_creator toneIndigo
```

## Components

### Episode Production

- [Episode Materials](https://github.com/thiet1910-bam/2d-illustrated-history/tree/main/episodes): `episodes`
- [Cluster Scanner](https://github.com/thiet1910-bam/2d-illustrated-history/blob/main/engine/scan_clusters.py): `engine/scan_clusters.py`
- [Wikimedia Image Finder](https://github.com/thiet1910-bam/2d-illustrated-history/blob/main/engine/fetch_wikimedia.py): `engine/fetch_wikimedia.py`

### Media Processing

- [Audio Mixer](https://github.com/thiet1910-bam/2d-illustrated-history/blob/main/engine/mix_audio.py): `engine/mix_audio.py`
- [BGM and SFX](https://github.com/thiet1910-bam/2d-illustrated-history/tree/main/shared): `shared`
- [Canvas Video Renderer](https://github.com/thiet1910-bam/2d-illustrated-history/blob/main/engine/render.js): `engine/render.js`

### Visual Toolkit

- [Brand Host](https://github.com/thiet1910-bam/2d-illustrated-history/blob/main/shared/ziro_kit/brand_host.js): `shared/ziro_kit/brand_host.js`
- [Skit Character Rig](https://github.com/thiet1910-bam/2d-illustrated-history/blob/main/shared/ziro_kit/skit_rig.js): `shared/ziro_kit/skit_rig.js`
- [Kinetic Typography](https://github.com/thiet1910-bam/2d-illustrated-history/blob/main/shared/ziro_kit/kinetic_type.js): `shared/ziro_kit/kinetic_type.js`
- [Map Drawing Tools](https://github.com/thiet1910-bam/2d-illustrated-history/blob/main/shared/ziro_kit/maps.js): `shared/ziro_kit/maps.js`
- [Drawing Helpers](https://github.com/thiet1910-bam/2d-illustrated-history/blob/main/shared/ziro_kit/helpers.js): `shared/ziro_kit/helpers.js`
- [Satellite Map](https://github.com/thiet1910-bam/2d-illustrated-history/tree/main/shared/maps): `shared/maps`

### Review and Delivery

- [Visual QA Sheet](https://github.com/thiet1910-bam/2d-illustrated-history/blob/main/engine/build_qa_sheet.py): `engine/build_qa_sheet.py`
- [Cluster Videos](https://github.com/thiet1910-bam/2d-illustrated-history/tree/main/episodes): `episodes`
- [Master Concatenator](https://github.com/thiet1910-bam/2d-illustrated-history/blob/main/engine/concat_master.py): `engine/concat_master.py`
- [Master Video](https://github.com/thiet1910-bam/2d-illustrated-history/tree/main/episodes): `episodes`

### Other components

- **Episode Creator**

## Connections

- Episode Creator → Episode Materials: creates (evidence: `README.md`)
- Episode Materials → Cluster Scanner: provides episode (evidence: `README.md`)
- Cluster Scanner → Audio Mixer: prepares cluster audio
- Audio Mixer → BGM and SFX: uses audio (evidence: `engine/mix_audio.py`)
- Audio Mixer → Canvas Video Renderer: mixes for rendering
- Wikimedia Image Finder → Satellite Map: complements maps
- Map Drawing Tools → Satellite Map: draws from (evidence: `README.md`)
- Brand Host → Drawing Helpers: uses helpers (evidence: `shared/ziro_kit/brand_host.js`)
- Skit Character Rig → Drawing Helpers: uses helpers (evidence: `shared/ziro_kit/skit_rig.js`)
- Kinetic Typography → Drawing Helpers: uses helpers (evidence: `shared/ziro_kit/kinetic_type.js`)
- Map Drawing Tools → Drawing Helpers: uses helpers (evidence: `shared/ziro_kit/maps.js`)
- Canvas Video Renderer → Cluster Videos: renders MP4 (evidence: `README.md`)
- Cluster Videos → Visual QA Sheet: checks rendered output (evidence: `README.md`)
- Cluster Videos → Master Concatenator: provides clusters (evidence: `README.md`)
- Master Concatenator → Master Video: concatenates (evidence: `README.md`)