# travisbuilds/duckduckgoose architecture

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

- Interactive diagram: https://gitdiagram.com/travisbuilds/duckduckgoose
- Repository: https://github.com/travisbuilds/duckduckgoose

## Overview

HFVG turns an episode brief into an approved, budget-controlled short video through a FastAPI/Next.js front end and durable Temporal workflows. The main path parses and plans a story, pauses for human approvals, generates and checks stills and clips, edits and adds audio, then gates final delivery. Separate branches cover cast assets, provider integrations, budget and model-limit safeguards, and retries/reconciliation. The README documents the end-to-end stages; some subsystem links rely on the source index because their implementation excerpts were not supplied.

Main entry points: [`hfvg/workflows/episode_v2.py`](https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/workflows/episode_v2.py) (Episode workflow), [`hfvg/activities/studio_generation.py`](https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/activities/studio_generation.py) (Still and clip generation), [`api/main.py`](https://github.com/travisbuilds/duckduckgoose/blob/main/api/main.py) (Studio API), [`hfvg/worker.py`](https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/worker.py) (Worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interfaces"]
  node_web["Studio UI<br/>[page.tsx]"]
  node_api["Studio API<br/>[main.py]"]
  node_cast_api["Cast routes<br/>[cast_routes.py]"]
end

subgraph group_orchestration["Workflow orchestration"]
  node_temporal["Temporal"]
  node_worker["Worker<br/>[worker.py]"]
  node_episode["Episode workflow<br/>[episode_v2.py]"]
  node_shot["Shot workflow<br/>[shot.py]"]
end

subgraph group_creation["Story and generation"]
  node_story["Story planning<br/>[story_shaping.py]"]
  node_shot_data["Shot plans<br/>[shot_data.py]"]
  node_cast["Cast assets<br/>[cast_plan.py]"]
  node_generation["Still and clip generation"]
  node_providers["AI providers<br/>[__init__.py]"]
end

subgraph group_controls["Safety and budget"]
  node_preflight["Preflight limits<br/>[preflight.py]"]
  node_budget[("Budget ledger<br/>[budget.py]")]
  node_qc["Quality gates<br/>[qc.py]"]
  node_studio_db[("Episode state<br/>[studio_db.py]")]
end

subgraph group_delivery["Media and delivery"]
  node_media["Edit and encode<br/>[media.py]"]
  node_audio["Audio generation<br/>[audio.py]"]
  node_audio_provider["ElevenLabs<br/>[elevenlabs.py]"]
  node_final["Final video<br/>[media.py]"]
end

node_creator(("Creator"))
node_human(("Human approver"))

node_creator -->|"manages episodes"| node_web
node_web -->|"uses API"| node_api
node_api -->|"starts workflows"| node_temporal
node_api -->|"reads and writes"| node_studio_db
node_api -->|"mounts routes"| node_cast_api
node_cast_api -.->|"uses cast state"| node_studio_db
node_temporal -->|"dispatches tasks"| node_worker
node_worker -->|"registers workflow"| node_episode
node_worker -->|"registers workflow"| node_shot
node_episode -.->|"shapes story"| node_story
node_episode -.->|"plans shots"| node_shot_data
node_episode -.->|"generates references"| node_cast
node_episode -->|"runs generation"| node_generation
node_shot -->|"runs shot jobs"| node_generation
node_generation -->|"submits requests"| node_providers
node_generation -->|"validates limits"| node_preflight
node_generation -->|"reserves spend"| node_budget
node_episode -->|"runs quality gates"| node_qc
node_episode -->|"tracks episode state"| node_studio_db
node_human -->|"approves gates"| node_episode
node_episode -->|"assembles edit"| node_media
node_episode -->|"generates audio"| node_audio
node_audio -->|"requests voiceover"| node_audio_provider
node_episode -->|"delivers video"| node_final
node_media -.->|"renders video"| node_final

click node_web "https://github.com/travisbuilds/duckduckgoose/blob/main/web/app/studio/episodes/%5Bid%5D/page.tsx"
click node_api "https://github.com/travisbuilds/duckduckgoose/blob/main/api/main.py"
click node_cast_api "https://github.com/travisbuilds/duckduckgoose/blob/main/api/cast_routes.py"
click node_worker "https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/worker.py"
click node_episode "https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/workflows/episode_v2.py"
click node_shot "https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/workflows/shot.py"
click node_story "https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/activities/story_shaping.py"
click node_shot_data "https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/shot_data.py"
click node_cast "https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/cast_plan.py"
click node_generation "https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/activities/studio_generation.py"
click node_providers "https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/providers/__init__.py"
click node_preflight "https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/preflight.py"
click node_budget "https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/budget.py"
click node_qc "https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/activities/qc.py"
click node_studio_db "https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/studio_db.py"
click node_media "https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/activities/media.py"
click node_audio "https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/activities/audio.py"
click node_audio_provider "https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/providers/elevenlabs.py"
click node_final "https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/activities/media.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_web,node_api,node_cast_api toneBlue
class node_temporal,node_worker,node_episode,node_shot toneAmber
class node_story,node_shot_data,node_cast,node_generation,node_providers toneMint
class node_preflight,node_budget,node_qc,node_studio_db toneRose
class node_media,node_audio,node_audio_provider,node_final,node_creator,node_human toneIndigo
```

## Components

### User interfaces

- [Studio UI](https://github.com/travisbuilds/duckduckgoose/blob/main/web/app/studio/episodes/%5Bid%5D/page.tsx): `web/app/studio/episodes/[id]/page.tsx`
- [Studio API](https://github.com/travisbuilds/duckduckgoose/blob/main/api/main.py): `api/main.py`
- [Cast routes](https://github.com/travisbuilds/duckduckgoose/blob/main/api/cast_routes.py): `api/cast_routes.py`

### Workflow orchestration

- **Temporal**
- [Worker](https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/worker.py): `hfvg/worker.py`
- [Episode workflow](https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/workflows/episode_v2.py): `hfvg/workflows/episode_v2.py`
- [Shot workflow](https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/workflows/shot.py): `hfvg/workflows/shot.py`

### Story and generation

- [Story planning](https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/activities/story_shaping.py): `hfvg/activities/story_shaping.py`
- [Shot plans](https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/shot_data.py): `hfvg/shot_data.py`
- [Cast assets](https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/cast_plan.py): `hfvg/cast_plan.py`
- [Still and clip generation](https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/activities/studio_generation.py): `hfvg/activities/studio_generation.py`
- [AI providers](https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/providers/__init__.py): `hfvg/providers/__init__.py`

### Safety and budget

- [Preflight limits](https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/preflight.py): `hfvg/preflight.py`
- [Budget ledger](https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/budget.py): `hfvg/budget.py`
- [Quality gates](https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/activities/qc.py): `hfvg/activities/qc.py`
- [Episode state](https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/studio_db.py): `hfvg/studio_db.py`

### Media and delivery

- [Edit and encode](https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/activities/media.py): `hfvg/activities/media.py`
- [Audio generation](https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/activities/audio.py): `hfvg/activities/audio.py`
- [ElevenLabs](https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/providers/elevenlabs.py): `hfvg/providers/elevenlabs.py`
- [Final video](https://github.com/travisbuilds/duckduckgoose/blob/main/hfvg/activities/media.py): `hfvg/activities/media.py`

### Other components

- **Creator**
- **Human approver**

## Connections

- Creator → Studio UI: manages episodes (evidence: `README.md`)
- Studio UI → Studio API: uses API (evidence: `README.md`)
- Studio API → Temporal: starts workflows (evidence: `README.md`)
- Studio API → Episode state: reads and writes (evidence: `api/main.py`)
- Studio API → Cast routes: mounts routes (evidence: `api/main.py`)
- Cast routes → Episode state: uses cast state
- Temporal → Worker: dispatches tasks (evidence: `README.md`)
- Worker → Episode workflow: registers workflow (evidence: `hfvg/worker.py`)
- Worker → Shot workflow: registers workflow (evidence: `hfvg/worker.py`)
- Episode workflow → Story planning: shapes story
- Episode workflow → Shot plans: plans shots
- Episode workflow → Cast assets: generates references
- Episode workflow → Still and clip generation: runs generation (evidence: `hfvg/workflows/episode_v2.py`)
- Shot workflow → Still and clip generation: runs shot jobs (evidence: `hfvg/workflows/shot.py`)
- Still and clip generation → AI providers: submits requests (evidence: `hfvg/activities/studio_generation.py`)
- Still and clip generation → Preflight limits: validates limits (evidence: `hfvg/activities/studio_generation.py`)
- Still and clip generation → Budget ledger: reserves spend (evidence: `hfvg/activities/studio_generation.py`)
- Episode workflow → Quality gates: runs quality gates (evidence: `hfvg/workflows/episode_v2.py`)
- Episode workflow → Episode state: tracks episode state (evidence: `hfvg/workflows/episode_v2.py`)
- Human approver → Episode workflow: approves gates (evidence: `README.md`)
- Episode workflow → Edit and encode: assembles edit (evidence: `README.md`)
- Episode workflow → Audio generation: generates audio (evidence: `README.md`)
- Audio generation → ElevenLabs: requests voiceover (evidence: `hfvg/activities/audio.py`)
- Episode workflow → Final video: delivers video (evidence: `README.md`)
- Edit and encode → Final video: renders video (evidence: `hfvg/activities/media.py`)
