# nnaligala/ai_videos architecture

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

- Interactive diagram: https://gitdiagram.com/nnaligala/ai_videos
- Repository: https://github.com/nnaligala/ai_videos

## Overview

This repository is an Agent Skill that guides a coding agent through evidence-gated production of an AI presenter video. The workflow starts with job setup and input approvals, then moves through script/narration, presenter generation, editing, rendering, and verification. Python scripts provide job initialization, input checks, pause-aware segment planning, and artifact-based state tracking; detailed creative and provider steps are documented in the skill and reference guides. Those guides and the finalization script were not sampled, so their internal calls are not inferred.

Main entry points: [`SKILL.md`](https://github.com/nnaligala/ai_videos/blob/main/SKILL.md) (Skill workflow), [`scripts/init_job.py`](https://github.com/nnaligala/ai_videos/blob/main/scripts/init_job.py) (Job initialization), [`scripts/preflight.py`](https://github.com/nnaligala/ai_videos/blob/main/scripts/preflight.py) (Input preflight), [`scripts/finalize_delivery.sh`](https://github.com/nnaligala/ai_videos/blob/main/scripts/finalize_delivery.sh) (Video rendering)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_job["Job and controls"]
  node_init["Job initialization<br/>[init_job.py]"]
  node_manifest["Job manifest<br/>[job.template.json]"]
  node_preflight["Input preflight<br/>[preflight.py]"]
  node_state["Evidence state checker<br/>[check_state.py]"]
  node_jobfiles[("Job artifacts")]
end

subgraph group_production["Video production"]
  node_skill["Skill workflow<br/>[SKILL.md]"]
  node_content["Script and narration<br/>[generation.md]"]
  node_segments["Pause-aware segments<br/>[plan_segments.py]"]
  node_presenter["Presenter generation<br/>[generation.md]"]
  node_editing["Audio-locked editing<br/>[editing.md]"]
end

subgraph group_delivery["Quality and delivery"]
  node_composition["Composition review<br/>[editing.md]"]
  node_render["Video rendering"]
  node_qa["Recovery and QA<br/>[qa-recovery.md]"]
  node_deliverables["Verified video package"]
end

node_agent(("Coding agent"))
node_ffmpeg["FFmpeg tools"]
node_providers["Generation providers"]

node_agent -->|"invokes"| node_skill
node_skill -->|"runs"| node_init
node_init -->|"loads template"| node_manifest
node_init -->|"creates job"| node_jobfiles
node_skill -->|"runs"| node_preflight
node_preflight -->|"probes media"| node_ffmpeg
node_preflight -->|"writes report"| node_jobfiles
node_skill -->|"guides"| node_content
node_content -.->|"records artifacts"| node_jobfiles
node_skill -->|"plans cuts"| node_segments
node_skill -->|"guides"| node_presenter
node_presenter -.->|"selects capability"| node_providers
node_skill -->|"guides"| node_editing
node_editing -.->|"previews"| node_composition
node_skill -->|"runs"| node_render
node_render -.->|"encodes and checks"| node_ffmpeg
node_render -->|"publishes"| node_deliverables
node_skill -->|"guides"| node_qa
node_skill -->|"runs checker"| node_state
node_state -->|"checks evidence"| node_jobfiles

click node_skill "https://github.com/nnaligala/ai_videos/blob/main/SKILL.md"
click node_init "https://github.com/nnaligala/ai_videos/blob/main/scripts/init_job.py"
click node_manifest "https://github.com/nnaligala/ai_videos/blob/main/assets/job.template.json"
click node_preflight "https://github.com/nnaligala/ai_videos/blob/main/scripts/preflight.py"
click node_content "https://github.com/nnaligala/ai_videos/blob/main/references/generation.md"
click node_segments "https://github.com/nnaligala/ai_videos/blob/main/scripts/plan_segments.py"
click node_presenter "https://github.com/nnaligala/ai_videos/blob/main/references/generation.md"
click node_editing "https://github.com/nnaligala/ai_videos/blob/main/references/editing.md"
click node_composition "https://github.com/nnaligala/ai_videos/blob/main/references/editing.md"
click node_render "https://github.com/nnaligala/ai_videos/blob/main/scripts/finalize_delivery.sh"
click node_qa "https://github.com/nnaligala/ai_videos/blob/main/references/qa-recovery.md"
click node_state "https://github.com/nnaligala/ai_videos/blob/main/scripts/check_state.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_init,node_manifest,node_preflight,node_state,node_jobfiles toneBlue
class node_skill,node_content,node_segments,node_presenter,node_editing toneAmber
class node_composition,node_render,node_qa,node_deliverables toneMint
class node_agent,node_ffmpeg,node_providers toneIndigo
```

## Components

### Job and controls

- [Job initialization](https://github.com/nnaligala/ai_videos/blob/main/scripts/init_job.py): `scripts/init_job.py`
- [Job manifest](https://github.com/nnaligala/ai_videos/blob/main/assets/job.template.json): `assets/job.template.json`
- [Input preflight](https://github.com/nnaligala/ai_videos/blob/main/scripts/preflight.py): `scripts/preflight.py`
- [Evidence state checker](https://github.com/nnaligala/ai_videos/blob/main/scripts/check_state.py): `scripts/check_state.py`
- **Job artifacts**

### Video production

- [Skill workflow](https://github.com/nnaligala/ai_videos/blob/main/SKILL.md): `SKILL.md`
- [Script and narration](https://github.com/nnaligala/ai_videos/blob/main/references/generation.md): `references/generation.md`
- [Pause-aware segments](https://github.com/nnaligala/ai_videos/blob/main/scripts/plan_segments.py): `scripts/plan_segments.py`
- [Presenter generation](https://github.com/nnaligala/ai_videos/blob/main/references/generation.md): `references/generation.md`
- [Audio-locked editing](https://github.com/nnaligala/ai_videos/blob/main/references/editing.md): `references/editing.md`

### Quality and delivery

- [Composition review](https://github.com/nnaligala/ai_videos/blob/main/references/editing.md): `references/editing.md`
- [Video rendering](https://github.com/nnaligala/ai_videos/blob/main/scripts/finalize_delivery.sh): `scripts/finalize_delivery.sh`
- [Recovery and QA](https://github.com/nnaligala/ai_videos/blob/main/references/qa-recovery.md): `references/qa-recovery.md`
- **Verified video package**

### Other components

- **Coding agent**
- **FFmpeg tools**
- **Generation providers**

## Connections

- Coding agent → Skill workflow: invokes (evidence: `README.md`)
- Skill workflow → Job initialization: runs (evidence: `README.md`)
- Job initialization → Job manifest: loads template (evidence: `scripts/init_job.py`)
- Job initialization → Job artifacts: creates job (evidence: `scripts/init_job.py`)
- Skill workflow → Input preflight: runs (evidence: `README.md`)
- Input preflight → FFmpeg tools: probes media (evidence: `scripts/preflight.py`)
- Input preflight → Job artifacts: writes report (evidence: `scripts/preflight.py`)
- Skill workflow → Script and narration: guides (evidence: `README.md`)
- Script and narration → Job artifacts: records artifacts (evidence: `README.md`)
- Skill workflow → Pause-aware segments: plans cuts (evidence: `README.md`)
- Skill workflow → Presenter generation: guides (evidence: `README.md`)
- Presenter generation → Generation providers: selects capability (evidence: `README.md`)
- Skill workflow → Audio-locked editing: guides (evidence: `README.md`)
- Audio-locked editing → Composition review: previews (evidence: `README.md`)
- Skill workflow → Video rendering: runs (evidence: `README.md`)
- Video rendering → FFmpeg tools: encodes and checks (evidence: `README.md`)
- Video rendering → Verified video package: publishes (evidence: `README.md`)
- Skill workflow → Recovery and QA: guides (evidence: `README.md`)
- Skill workflow → Evidence state checker: runs checker (evidence: `README.md`)
- Evidence state checker → Job artifacts: checks evidence (evidence: `scripts/check_state.py`)
