# stagehandcuff/ai-motion-graphics-generator architecture

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

- Interactive diagram: https://gitdiagram.com/stagehandcuff/ai-motion-graphics-generator
- Repository: https://github.com/stagehandcuff/ai-motion-graphics-generator

## Overview

This repository contains a compact motion-graphics pipeline: handlers normalize script, storyboard, or reference-clip inputs into scene graphs, and ordered processors plan scenes, generate keyframes, and budget tween frames. The README describes a much broader desktop product, but those subsystems are not present in the supplied tree, so they are not expanded into implementation nodes. The shown keyframe processor calls a model router whose source is absent. The excerpts do not show how ingest connects to the processor pipeline or how results are rendered/exported.

Main entry points: [`processors/keyframe_processor.py`](https://github.com/stagehandcuff/ai-motion-graphics-generator/blob/main/processors/keyframe_processor.py) (Keyframe Processor), [`processors/scene_planner.py`](https://github.com/stagehandcuff/ai-motion-graphics-generator/blob/main/processors/scene_planner.py) (Scene Planner), [`handlers/storyboard_handler.py`](https://github.com/stagehandcuff/ai-motion-graphics-generator/blob/main/handlers/storyboard_handler.py) (Storyboard Ingest), [`handlers/script_handler.py`](https://github.com/stagehandcuff/ai-motion-graphics-generator/blob/main/handlers/script_handler.py) (Script Ingest)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Input Ingest"]
  node_storyboard["Storyboard Ingest"]
  node_script["Script Ingest<br/>[script_handler.py]"]
  node_clip["Clip Ingest<br/>[clip_handler.py]"]
end

subgraph group_processing["Scene Processing"]
  node_planner["Scene Planner<br/>[scene_planner.py]"]
  node_keyframes["Keyframe Processor"]
  node_tween["Tween Processor<br/>[tween_processor.py]"]
  node_modelrouter["Model Router"]
end

subgraph group_launch["Launch Interfaces"]
  node_gui["GUI Entry<br/>[app.py]"]
  node_cli["CLI Entry<br/>[cli.py]"]
end

node_creator(("Creator"))

node_creator -->|"provides storyboard"| node_storyboard
node_creator -->|"provides script"| node_script
node_creator -->|"provides reference clip"| node_clip
node_planner -->|"precedes"| node_keyframes
node_keyframes -->|"precedes"| node_tween
node_keyframes -->|"requests keyframes"| node_modelrouter

click node_storyboard "https://github.com/stagehandcuff/ai-motion-graphics-generator/blob/main/handlers/storyboard_handler.py"
click node_script "https://github.com/stagehandcuff/ai-motion-graphics-generator/blob/main/handlers/script_handler.py"
click node_clip "https://github.com/stagehandcuff/ai-motion-graphics-generator/blob/main/handlers/clip_handler.py"
click node_planner "https://github.com/stagehandcuff/ai-motion-graphics-generator/blob/main/processors/scene_planner.py"
click node_keyframes "https://github.com/stagehandcuff/ai-motion-graphics-generator/blob/main/processors/keyframe_processor.py"
click node_tween "https://github.com/stagehandcuff/ai-motion-graphics-generator/blob/main/processors/tween_processor.py"
click node_gui "https://github.com/stagehandcuff/ai-motion-graphics-generator/blob/main/bootstrap/app.py"
click node_cli "https://github.com/stagehandcuff/ai-motion-graphics-generator/blob/main/bootstrap/cli.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_storyboard,node_script,node_clip toneBlue
class node_planner,node_keyframes,node_tween,node_modelrouter toneAmber
class node_gui,node_cli toneMint
class node_creator toneIndigo
```

## Components

### Input Ingest

- [Storyboard Ingest](https://github.com/stagehandcuff/ai-motion-graphics-generator/blob/main/handlers/storyboard_handler.py): `handlers/storyboard_handler.py`
- [Script Ingest](https://github.com/stagehandcuff/ai-motion-graphics-generator/blob/main/handlers/script_handler.py): `handlers/script_handler.py`
- [Clip Ingest](https://github.com/stagehandcuff/ai-motion-graphics-generator/blob/main/handlers/clip_handler.py): `handlers/clip_handler.py`

### Scene Processing

- [Scene Planner](https://github.com/stagehandcuff/ai-motion-graphics-generator/blob/main/processors/scene_planner.py): `processors/scene_planner.py`
- [Keyframe Processor](https://github.com/stagehandcuff/ai-motion-graphics-generator/blob/main/processors/keyframe_processor.py): `processors/keyframe_processor.py`
- [Tween Processor](https://github.com/stagehandcuff/ai-motion-graphics-generator/blob/main/processors/tween_processor.py): `processors/tween_processor.py`
- **Model Router**

### Launch Interfaces

- [GUI Entry](https://github.com/stagehandcuff/ai-motion-graphics-generator/blob/main/bootstrap/app.py): `bootstrap/app.py`
- [CLI Entry](https://github.com/stagehandcuff/ai-motion-graphics-generator/blob/main/bootstrap/cli.py): `bootstrap/cli.py`

### Other components

- **Creator**

## Connections

- Creator → Storyboard Ingest: provides storyboard (evidence: `README.md`)
- Creator → Script Ingest: provides script (evidence: `README.md`)
- Creator → Clip Ingest: provides reference clip (evidence: `README.md`)
- Scene Planner → Keyframe Processor: precedes (evidence: `processors/__init__.py`)
- Keyframe Processor → Tween Processor: precedes (evidence: `processors/__init__.py`)
- Keyframe Processor → Model Router: requests keyframes (evidence: `processors/keyframe_processor.py`)