# aldegad/sprite-gen architecture

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

- Interactive diagram: https://gitdiagram.com/aldegad/sprite-gen
- Repository: https://github.com/aldegad/sprite-gen

## Overview

sprite-gen is a Python CLI and optional webview for turning still images into transparent game sprites. Its primary atlas workflow prepares a run, generates state rows, extracts clean frames, and composes an atlas with frame-layout metadata; optional curation adjusts the bake without rewriting source frames. A separate still-to-video workflow produces transparent motion loops. The README also documents independent image utilities, deterministic post-processing, asset tools, and optional scene rendering. The graph follows the documented pipeline map; unsampled command internals are represented only where that map supports them.

Main entry points: [`sprite_gen/cli.py`](https://github.com/aldegad/sprite-gen/blob/main/sprite_gen/cli.py) (Command router), [`sprite_gen/compose/compose_atlas.py`](https://github.com/aldegad/sprite-gen/blob/main/sprite_gen/compose/compose_atlas.py) (Compose atlas), [`sprite_gen/gen/gen_set.py`](https://github.com/aldegad/sprite-gen/blob/main/sprite_gen/gen/gen_set.py) (Generate rows), [`sprite_gen/gen/video.py`](https://github.com/aldegad/sprite-gen/blob/main/sprite_gen/gen/video.py) (Animate still)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and workflow"]
  node_cli["Command router<br/>[cli.py]"]
end

subgraph group_atlas["Atlas pipeline"]
  node_prepare["Prepare run<br/>[prepare.py]"]
  node_generate["Generate rows<br/>[gen_set.py]"]
  node_extract["Extract frames<br/>[extract.py]"]
  node_compose["Compose atlas<br/>[compose_atlas.py]"]
  node_atlas_result["Atlas and manifest"]
end

subgraph group_curation["Curation and QA"]
  node_curation_server["Curation webview<br/>[serve_curation.py]"]
  node_curation_data["Curation sidecar<br/>[curation.py]"]
  node_breathe["Idle breathing<br/>[breathe.py]"]
  node_qa["Motion QA<br/>[preview.py]"]
end

subgraph group_video["Video pipeline"]
  node_video_canvas["Video canvas<br/>[canvas.py]"]
  node_video_gen["Animate still<br/>[video.py]"]
  node_video_frames["Extract video frames<br/>[frames.py]"]
  node_video_loop["Cut seamless loop<br/>[loop.py]"]
  node_loop_result["Transparent loop outputs"]
end

subgraph group_assets["Asset tools and scenes"]
  node_postprocess["Recolor and exports"]
  node_asset_tools["Independent asset tools"]
  node_scene["Scene composition"]
end

node_user(("Sprite creator"))
node_provider{{"Image model"}}
node_video_model{{"Video model"}}

node_user -->|"runs commands"| node_cli
node_cli -->|"dispatches prepare"| node_prepare
node_cli -->|"dispatches gen-set"| node_generate
node_cli -->|"dispatches extract"| node_extract
node_cli -->|"dispatches compose"| node_compose
node_prepare -->|"provides run recipe"| node_generate
node_generate -->|"requests row images"| node_provider
node_generate -->|"provides generated rows"| node_extract
node_extract -->|"provides transparent frames"| node_compose
node_compose -->|"writes atlas and layout"| node_atlas_result
node_user -.->|"opens optional editor"| node_curation_server
node_curation_server -->|"reads and saves choices"| node_curation_data
node_curation_data -.->|"supplies frame edits"| node_compose
node_compose -->|"applies idle motion"| node_breathe
node_cli -->|"dispatches preview"| node_qa
node_qa -->|"reads extracted frames"| node_atlas_result
node_cli -->|"dispatches video-canvas"| node_video_canvas
node_video_canvas -->|"prepares canvas"| node_video_gen
node_video_gen -->|"requests animation"| node_video_model
node_video_gen -->|"provides source clip"| node_video_frames
node_video_frames -->|"provides keyed frames"| node_video_loop
node_video_loop -->|"writes loop assets"| node_loop_result
node_cli -->|"dispatches post-processing"| node_postprocess
node_cli -->|"dispatches asset tools"| node_asset_tools
node_cli -->|"dispatches scene tools"| node_scene
node_atlas_result -.->|"consumes finished assets"| node_scene

click node_cli "https://github.com/aldegad/sprite-gen/blob/main/sprite_gen/cli.py"
click node_prepare "https://github.com/aldegad/sprite-gen/blob/main/sprite_gen/gen/prepare.py"
click node_generate "https://github.com/aldegad/sprite-gen/blob/main/sprite_gen/gen/gen_set.py"
click node_extract "https://github.com/aldegad/sprite-gen/blob/main/sprite_gen/frames/extract.py"
click node_compose "https://github.com/aldegad/sprite-gen/blob/main/sprite_gen/compose/compose_atlas.py"
click node_curation_server "https://github.com/aldegad/sprite-gen/blob/main/sprite_gen/serve/serve_curation.py"
click node_curation_data "https://github.com/aldegad/sprite-gen/blob/main/sprite_gen/curate/curation.py"
click node_breathe "https://github.com/aldegad/sprite-gen/blob/main/sprite_gen/effects/breathe.py"
click node_qa "https://github.com/aldegad/sprite-gen/blob/main/sprite_gen/qa/preview.py"
click node_video_canvas "https://github.com/aldegad/sprite-gen/blob/main/sprite_gen/video/canvas.py"
click node_video_gen "https://github.com/aldegad/sprite-gen/blob/main/sprite_gen/gen/video.py"
click node_video_frames "https://github.com/aldegad/sprite-gen/blob/main/sprite_gen/video/frames.py"
click node_video_loop "https://github.com/aldegad/sprite-gen/blob/main/sprite_gen/video/loop.py"
click node_postprocess "https://github.com/aldegad/sprite-gen/tree/main/sprite_gen/compose"
click node_asset_tools "https://github.com/aldegad/sprite-gen/tree/main/sprite_gen/background"
click node_scene "https://github.com/aldegad/sprite-gen/tree/main/sprite_gen/scene"

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_cli toneBlue
class node_prepare,node_generate,node_extract,node_compose,node_atlas_result toneAmber
class node_curation_server,node_curation_data,node_breathe,node_qa toneMint
class node_video_canvas,node_video_gen,node_video_frames,node_video_loop,node_loop_result toneRose
class node_postprocess,node_asset_tools,node_scene,node_user,node_provider,node_video_model toneIndigo
```

## Components

### CLI and workflow

- [Command router](https://github.com/aldegad/sprite-gen/blob/main/sprite_gen/cli.py): `sprite_gen/cli.py`

### Atlas pipeline

- [Prepare run](https://github.com/aldegad/sprite-gen/blob/main/sprite_gen/gen/prepare.py): `sprite_gen/gen/prepare.py`
- [Generate rows](https://github.com/aldegad/sprite-gen/blob/main/sprite_gen/gen/gen_set.py): `sprite_gen/gen/gen_set.py`
- [Extract frames](https://github.com/aldegad/sprite-gen/blob/main/sprite_gen/frames/extract.py): `sprite_gen/frames/extract.py`
- [Compose atlas](https://github.com/aldegad/sprite-gen/blob/main/sprite_gen/compose/compose_atlas.py): `sprite_gen/compose/compose_atlas.py`
- **Atlas and manifest**

### Curation and QA

- [Curation webview](https://github.com/aldegad/sprite-gen/blob/main/sprite_gen/serve/serve_curation.py): `sprite_gen/serve/serve_curation.py`
- [Curation sidecar](https://github.com/aldegad/sprite-gen/blob/main/sprite_gen/curate/curation.py): `sprite_gen/curate/curation.py`
- [Idle breathing](https://github.com/aldegad/sprite-gen/blob/main/sprite_gen/effects/breathe.py): `sprite_gen/effects/breathe.py`
- [Motion QA](https://github.com/aldegad/sprite-gen/blob/main/sprite_gen/qa/preview.py): `sprite_gen/qa/preview.py`

### Video pipeline

- [Video canvas](https://github.com/aldegad/sprite-gen/blob/main/sprite_gen/video/canvas.py): `sprite_gen/video/canvas.py`
- [Animate still](https://github.com/aldegad/sprite-gen/blob/main/sprite_gen/gen/video.py): `sprite_gen/gen/video.py`
- [Extract video frames](https://github.com/aldegad/sprite-gen/blob/main/sprite_gen/video/frames.py): `sprite_gen/video/frames.py`
- [Cut seamless loop](https://github.com/aldegad/sprite-gen/blob/main/sprite_gen/video/loop.py): `sprite_gen/video/loop.py`
- **Transparent loop outputs**

### Asset tools and scenes

- [Recolor and exports](https://github.com/aldegad/sprite-gen/tree/main/sprite_gen/compose): `sprite_gen/compose`
- [Independent asset tools](https://github.com/aldegad/sprite-gen/tree/main/sprite_gen/background): `sprite_gen/background`
- [Scene composition](https://github.com/aldegad/sprite-gen/tree/main/sprite_gen/scene): `sprite_gen/scene`

### Other components

- **Sprite creator**
- **Image model**
- **Video model**

## Connections

- Sprite creator → Command router: runs commands
- Command router → Prepare run: dispatches prepare
- Command router → Generate rows: dispatches gen-set
- Command router → Extract frames: dispatches extract
- Command router → Compose atlas: dispatches compose
- Prepare run → Generate rows: provides run recipe
- Generate rows → Image model: requests row images
- Generate rows → Extract frames: provides generated rows
- Extract frames → Compose atlas: provides transparent frames
- Compose atlas → Atlas and manifest: writes atlas and layout
- Sprite creator → Curation webview: opens optional editor
- Curation webview → Curation sidecar: reads and saves choices
- Curation sidecar → Compose atlas: supplies frame edits
- Compose atlas → Idle breathing: applies idle motion
- Command router → Motion QA: dispatches preview
- Motion QA → Atlas and manifest: reads extracted frames
- Command router → Video canvas: dispatches video-canvas
- Video canvas → Animate still: prepares canvas
- Animate still → Video model: requests animation
- Animate still → Extract video frames: provides source clip
- Extract video frames → Cut seamless loop: provides keyed frames
- Cut seamless loop → Transparent loop outputs: writes loop assets
- Command router → Recolor and exports: dispatches post-processing
- Command router → Independent asset tools: dispatches asset tools
- Command router → Scene composition: dispatches scene tools
- Atlas and manifest → Scene composition: consumes finished assets