# achimala/dream-loop architecture

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

- Interactive diagram: https://gitdiagram.com/achimala/dream-loop
- Repository: https://github.com/achimala/dream-loop

## Overview

dream-loop is an agent skill for iteratively building visually polished games, apps, or scenes. Its principal workflow is to generate a visual target, implement toward it, capture the running result, and have a separate vision-capable critic recommend changes; the agent repeats implementation and critique, optionally generating a better target. The repository also documents Plus and Pro workflows and includes a local preview/capture server and a Fal queue helper for image-to-3D assets. Source excerpts are partial, so the graph omits uncertain internal wiring from the skill references.

Main entry points: [`scripts/fal-batch.mjs`](https://github.com/achimala/dream-loop/blob/main/scripts/fal-batch.mjs) (Fal batch helper), [`scripts/preview-server.py`](https://github.com/achimala/dream-loop/blob/main/scripts/preview-server.py) (Preview server), [`SKILL.md`](https://github.com/achimala/dream-loop/blob/main/SKILL.md) (Dream-loop skill), [`references/plus-mode/workflow.md`](https://github.com/achimala/dream-loop/blob/main/references/plus-mode/workflow.md) (Plus workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Visual iteration"]
  node_skill["Dream-loop skill<br/>[SKILL.md]"]
  node_plus["Plus workflow<br/>[workflow.md]"]
  node_pro["Pro workflow<br/>[workflow.md]"]
end

subgraph group_assets["Asset generation"]
  node_plus3d["Plus 3D assets<br/>[assets-3d.md]"]
  node_pro3d["Pro 3D assets<br/>[assets-3d.md]"]
  node_falbatch["Fal batch helper<br/>[fal-batch.mjs]"]
  node_plan["Job plan and state"]
  node_images[("Input images")]
  node_models[("Downloaded GLB models")]
end

subgraph group_runtime["Preview and capture"]
  node_preview["Preview server<br/>[preview-server.py]"]
  node_capture[("Screenshot captures")]
end

node_user(("User"))
node_agent(("AI agent"))
node_targetgen(("Image generation"))
node_app["Built app or scene"]
node_critic(("Vision critic"))
node_fal(("Fal queue API"))

node_user -->|"requests build"| node_agent
node_agent -->|"follows workflow"| node_skill
node_skill -->|"generates target"| node_targetgen
node_agent -->|"implements target"| node_app
node_agent -->|"starts preview"| node_preview
node_preview -->|"serves workspace"| node_app
node_agent -->|"requests capture"| node_preview
node_preview -->|"writes PNG"| node_capture
node_agent -->|"requests critique"| node_critic
node_capture -->|"provides screenshot"| node_critic
node_critic -->|"returns feedback"| node_agent
node_agent -.->|"may follow"| node_plus
node_agent -.->|"may follow"| node_pro
node_plus -.->|"documents assets"| node_plus3d
node_pro -.->|"documents assets"| node_pro3d
node_agent -.->|"runs asset jobs"| node_falbatch
node_falbatch -->|"reads and updates"| node_plan
node_falbatch -->|"reads inputs"| node_images
node_falbatch -->|"submits and collects"| node_fal
node_falbatch -->|"downloads GLB"| node_models

click node_skill "https://github.com/achimala/dream-loop/blob/main/SKILL.md"
click node_plus "https://github.com/achimala/dream-loop/blob/main/references/plus-mode/workflow.md"
click node_pro "https://github.com/achimala/dream-loop/blob/main/references/pro-mode/workflow.md"
click node_plus3d "https://github.com/achimala/dream-loop/blob/main/references/plus-mode/assets-3d.md"
click node_pro3d "https://github.com/achimala/dream-loop/blob/main/references/pro-mode/assets-3d.md"
click node_preview "https://github.com/achimala/dream-loop/blob/main/scripts/preview-server.py"
click node_falbatch "https://github.com/achimala/dream-loop/blob/main/scripts/fal-batch.mjs"

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_skill,node_plus,node_pro,node_user toneBlue
class node_plus3d,node_pro3d,node_falbatch,node_plan,node_images,node_models toneAmber
class node_preview,node_capture toneMint
class node_agent,node_targetgen,node_app,node_critic toneIndigo
class node_fal toneRose
```

## Components

### Visual iteration

- [Dream-loop skill](https://github.com/achimala/dream-loop/blob/main/SKILL.md): `SKILL.md`
- [Plus workflow](https://github.com/achimala/dream-loop/blob/main/references/plus-mode/workflow.md): `references/plus-mode/workflow.md`
- [Pro workflow](https://github.com/achimala/dream-loop/blob/main/references/pro-mode/workflow.md): `references/pro-mode/workflow.md`

### Asset generation

- [Plus 3D assets](https://github.com/achimala/dream-loop/blob/main/references/plus-mode/assets-3d.md): `references/plus-mode/assets-3d.md`
- [Pro 3D assets](https://github.com/achimala/dream-loop/blob/main/references/pro-mode/assets-3d.md): `references/pro-mode/assets-3d.md`
- [Fal batch helper](https://github.com/achimala/dream-loop/blob/main/scripts/fal-batch.mjs): `scripts/fal-batch.mjs`
- **Job plan and state**
- **Input images**
- **Downloaded GLB models**

### Preview and capture

- [Preview server](https://github.com/achimala/dream-loop/blob/main/scripts/preview-server.py): `scripts/preview-server.py`
- **Screenshot captures**

### Other components

- **User**
- **AI agent**
- **Image generation**
- **Built app or scene**
- **Vision critic**
- **Fal queue API**

## Connections

- User → AI agent: requests build
- AI agent → Dream-loop skill: follows workflow
- Dream-loop skill → Image generation: generates target
- AI agent → Built app or scene: implements target
- AI agent → Preview server: starts preview
- Preview server → Built app or scene: serves workspace
- AI agent → Preview server: requests capture
- Preview server → Screenshot captures: writes PNG
- AI agent → Vision critic: requests critique
- Screenshot captures → Vision critic: provides screenshot
- Vision critic → AI agent: returns feedback
- AI agent → Plus workflow: may follow
- AI agent → Pro workflow: may follow
- Plus workflow → Plus 3D assets: documents assets
- Pro workflow → Pro 3D assets: documents assets
- AI agent → Fal batch helper: runs asset jobs
- Fal batch helper → Job plan and state: reads and updates
- Fal batch helper → Input images: reads inputs
- Fal batch helper → Fal queue API: submits and collects
- Fal batch helper → Downloaded GLB models: downloads GLB