# kleinflow/kleinflow architecture

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

- Interactive diagram: https://gitdiagram.com/kleinflow/kleinflow
- Repository: https://github.com/kleinflow/kleinflow

## Overview

KleinFlow is a local Gradio animation studio that turns user render settings, prompts, motion controls, and optional audio/video references into generated frames and exported video. The principal workflow is UI submission → validated frame planning → FLUX.2 Klein generation → temporal/color/post-processing → output files. The graph preserves documented branches such as VeloSeq, depth motion, semantic masks, interpolation, and upscaling. Some feature wiring is inferred only from documented responsibilities because several implementation files were not sampled; those uncertain edges are omitted.

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Interface &amp; Control"]
  node_studio["Gradio Studio<br/>[app.py]"]
  node_settings["Render Settings<br/>[settings.py]"]
end

subgraph group_planning["Animation Planning"]
  node_veloseq["VeloSeq Planner<br/>[veloseq.py]"]
  node_audio["Audio Reactive<br/>[audio_reactive.py]"]
  node_motion["Camera Depth Motion<br/>[transform.py]"]
  node_video_reference["Video Reference<br/>[video_reference.py]"]
  node_semantic["Semantic Masking"]
end

subgraph group_generation["Generation &amp; Models"]
  node_renderer["Render Engine<br/>[renderer.py]"]
  node_backend["Klein FP8 Backend<br/>[klein_fp8.py]"]
end

subgraph group_processing["Temporal &amp; Output"]
  node_temporal["Temporal Stack<br/>[temporal.py]"]
  node_color["Color Polish<br/>[final_polish.py]"]
  node_interpolation["Frame Interpolation"]
  node_upscaler["Flow Upscaler"]
  node_video["Video Export<br/>[video.py]"]
end

subgraph group_runtime["Portable Runtime"]
  node_launcher["Application Launcher<br/>[app.py]"]
  node_manifest["Model Manifest<br/>[model_manifest.py]"]
  node_model_files[("Local Model Files<br/>[model_manifest.py]")]
  node_outputs[("Output Workspace<br/>[paths.py]")]
  node_portable["Portable Paths<br/>[paths.py]"]
end

node_user(("Animator"))

node_user -->|"submits render"| node_studio
node_launcher -->|"launches UI"| node_studio
node_studio -->|"edits settings"| node_settings
node_studio -->|"starts render"| node_renderer
node_renderer -->|"validates settings"| node_settings
node_renderer -->|"plans frames"| node_veloseq
node_audio -->|"injects controls"| node_veloseq
node_renderer -->|"applies motion"| node_motion
node_renderer -->|"reads reference"| node_video_reference
node_renderer -->|"routes masks"| node_semantic
node_renderer -->|"generates frames"| node_backend
node_backend -->|"loads models"| node_model_files
node_manifest -->|"validates files"| node_model_files
node_renderer -->|"stabilizes frames"| node_temporal
node_renderer -->|"polishes frames"| node_color
node_renderer -->|"interpolates frames"| node_interpolation
node_renderer -.->|"upscales output"| node_upscaler
node_renderer -->|"exports video"| node_video
node_video -->|"writes results"| node_outputs
node_portable -->|"resolves paths"| node_outputs
node_studio -->|"shows results"| node_user

click node_launcher "https://github.com/kleinflow/kleinflow/blob/main/app.py"
click node_studio "https://github.com/kleinflow/kleinflow/blob/main/kleinflow/ui/app.py"
click node_settings "https://github.com/kleinflow/kleinflow/blob/main/kleinflow/core/settings.py"
click node_renderer "https://github.com/kleinflow/kleinflow/blob/main/kleinflow/core/renderer.py"
click node_veloseq "https://github.com/kleinflow/kleinflow/blob/main/kleinflow/core/veloseq.py"
click node_audio "https://github.com/kleinflow/kleinflow/blob/main/kleinflow/core/audio_reactive.py"
click node_motion "https://github.com/kleinflow/kleinflow/blob/main/kleinflow/core/transform.py"
click node_video_reference "https://github.com/kleinflow/kleinflow/blob/main/kleinflow/core/video_reference.py"
click node_semantic "https://github.com/kleinflow/kleinflow/blob/main/kleinflow/core/semantic_masking.py"
click node_backend "https://github.com/kleinflow/kleinflow/blob/main/kleinflow/backends/klein_fp8.py"
click node_manifest "https://github.com/kleinflow/kleinflow/blob/main/kleinflow/model_manifest.py"
click node_model_files "https://github.com/kleinflow/kleinflow/blob/main/kleinflow/model_manifest.py"
click node_temporal "https://github.com/kleinflow/kleinflow/blob/main/kleinflow/core/temporal.py"
click node_color "https://github.com/kleinflow/kleinflow/blob/main/kleinflow/core/final_polish.py"
click node_interpolation "https://github.com/kleinflow/kleinflow/blob/main/kleinflow/core/frame_interpolation.py"
click node_upscaler "https://github.com/kleinflow/kleinflow/blob/main/kleinflow/backends/flow_upscaler_unet.py"
click node_video "https://github.com/kleinflow/kleinflow/blob/main/kleinflow/core/video.py"
click node_outputs "https://github.com/kleinflow/kleinflow/blob/main/kleinflow/paths.py"
click node_portable "https://github.com/kleinflow/kleinflow/blob/main/kleinflow/paths.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_studio,node_settings toneBlue
class node_veloseq,node_audio,node_motion,node_video_reference,node_semantic toneAmber
class node_renderer,node_backend toneMint
class node_temporal,node_color,node_interpolation,node_upscaler,node_video toneRose
class node_launcher,node_manifest,node_model_files,node_outputs,node_portable,node_user toneIndigo
```

## Components

### Interface & Control

- [Gradio Studio](https://github.com/kleinflow/kleinflow/blob/main/kleinflow/ui/app.py): `kleinflow/ui/app.py`
- [Render Settings](https://github.com/kleinflow/kleinflow/blob/main/kleinflow/core/settings.py): `kleinflow/core/settings.py`

### Animation Planning

- [VeloSeq Planner](https://github.com/kleinflow/kleinflow/blob/main/kleinflow/core/veloseq.py): `kleinflow/core/veloseq.py`
- [Audio Reactive](https://github.com/kleinflow/kleinflow/blob/main/kleinflow/core/audio_reactive.py): `kleinflow/core/audio_reactive.py`
- [Camera Depth Motion](https://github.com/kleinflow/kleinflow/blob/main/kleinflow/core/transform.py): `kleinflow/core/transform.py`
- [Video Reference](https://github.com/kleinflow/kleinflow/blob/main/kleinflow/core/video_reference.py): `kleinflow/core/video_reference.py`
- [Semantic Masking](https://github.com/kleinflow/kleinflow/blob/main/kleinflow/core/semantic_masking.py): `kleinflow/core/semantic_masking.py`

### Generation & Models

- [Render Engine](https://github.com/kleinflow/kleinflow/blob/main/kleinflow/core/renderer.py): `kleinflow/core/renderer.py`
- [Klein FP8 Backend](https://github.com/kleinflow/kleinflow/blob/main/kleinflow/backends/klein_fp8.py): `kleinflow/backends/klein_fp8.py`

### Temporal & Output

- [Temporal Stack](https://github.com/kleinflow/kleinflow/blob/main/kleinflow/core/temporal.py): `kleinflow/core/temporal.py`
- [Color Polish](https://github.com/kleinflow/kleinflow/blob/main/kleinflow/core/final_polish.py): `kleinflow/core/final_polish.py`
- [Frame Interpolation](https://github.com/kleinflow/kleinflow/blob/main/kleinflow/core/frame_interpolation.py): `kleinflow/core/frame_interpolation.py`
- [Flow Upscaler](https://github.com/kleinflow/kleinflow/blob/main/kleinflow/backends/flow_upscaler_unet.py): `kleinflow/backends/flow_upscaler_unet.py`
- [Video Export](https://github.com/kleinflow/kleinflow/blob/main/kleinflow/core/video.py): `kleinflow/core/video.py`

### Portable Runtime

- [Application Launcher](https://github.com/kleinflow/kleinflow/blob/main/app.py): `app.py`
- [Model Manifest](https://github.com/kleinflow/kleinflow/blob/main/kleinflow/model_manifest.py): `kleinflow/model_manifest.py`
- [Local Model Files](https://github.com/kleinflow/kleinflow/blob/main/kleinflow/model_manifest.py): `kleinflow/model_manifest.py`
- [Output Workspace](https://github.com/kleinflow/kleinflow/blob/main/kleinflow/paths.py): `kleinflow/paths.py`
- [Portable Paths](https://github.com/kleinflow/kleinflow/blob/main/kleinflow/paths.py): `kleinflow/paths.py`

### Other components

- **Animator**

## Connections

- Animator → Gradio Studio: submits render
- Application Launcher → Gradio Studio: launches UI
- Gradio Studio → Render Settings: edits settings
- Gradio Studio → Render Engine: starts render
- Render Engine → Render Settings: validates settings
- Render Engine → VeloSeq Planner: plans frames
- Audio Reactive → VeloSeq Planner: injects controls
- Render Engine → Camera Depth Motion: applies motion
- Render Engine → Video Reference: reads reference
- Render Engine → Semantic Masking: routes masks
- Render Engine → Klein FP8 Backend: generates frames
- Klein FP8 Backend → Local Model Files: loads models
- Model Manifest → Local Model Files: validates files
- Render Engine → Temporal Stack: stabilizes frames
- Render Engine → Color Polish: polishes frames
- Render Engine → Frame Interpolation: interpolates frames
- Render Engine → Flow Upscaler: upscales output
- Render Engine → Video Export: exports video
- Video Export → Output Workspace: writes results
- Portable Paths → Output Workspace: resolves paths
- Gradio Studio → Animator: shows results
