# sloemo01/diorama architecture

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

- Interactive diagram: https://gitdiagram.com/sloemo01/diorama
- Repository: https://github.com/sloemo01/diorama

## Overview

Diorama is an agent-oriented playbook and copy-in code kit for building deterministic, rotatable Three.js dioramas. Its documented workflow is to research a subject and assets, choose a visual look and asset-sourcing approach, build a scene from selected templates, then capture and inspect frames with the QA harness. The templates provide scene, animation, presentation, and rendering building blocks; verification examples demonstrate their use. Evidence is limited to the README and sampled files, so unsampled template relationships are not inferred.

Main entry points: [`README.md`](https://github.com/sloemo01/diorama/blob/main/README.md) (Build playbook), [`verify/water/src/main.js`](https://github.com/sloemo01/diorama/blob/main/verify/water/src/main.js) (Pool scene entry), [`bin.js`](https://github.com/sloemo01/diorama/blob/main/bin.js) (Installer CLI), [`templates/pixel-stroke.js`](https://github.com/sloemo01/diorama/blob/main/templates/pixel-stroke.js) (Pixel stroke)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Playbook workflow"]
  node_cli["Installer CLI<br/>[bin.js]"]
  node_playbook["Build playbook<br/>[README.md]"]
end

subgraph group_scene["Scene toolkit"]
  node_scene_contract["Scene contract<br/>[scene-contract.js]"]
  node_geometry["Geometry helpers<br/>[geometry.js]"]
  node_construction["Construction kit"]
  node_people["People models<br/>[peopleModel.js]"]
  node_street_people["Street people"]
  node_poses["Pose library<br/>[poses.js]"]
  node_transfer["Motion transfer<br/>[transfer.js]"]
  node_combat["Combat motion<br/>[combat.js]"]
end

subgraph group_looks["Looks and rendering"]
  node_orbit["Camera orbit<br/>[orbit.js]"]
  node_pixel_post["Pixel stroke<br/>[pixel-stroke.js]"]
  node_toon["Stroked toon<br/>[stroked-toon.js]"]
end

subgraph group_examples["Worked scenes"]
  node_water_main["Pool scene entry<br/>[main.js]"]
  node_water_camera["Pool camera<br/>[camera.js]"]
  node_water_lighting["Pool lighting<br/>[lighting.js]"]
  node_water_surface["Water surface<br/>[water.js]"]
  node_water_wake["Wake effects<br/>[wake.js]"]
  node_water_splash["Splash effects<br/>[splash.js]"]
  node_post["Pixel postprocess<br/>[post.js]"]
  node_palette["Color palette<br/>[palette.js]"]
end

subgraph group_qa["Quality checks"]
  node_qa_frames["Frame capture<br/>[frames.mjs]"]
  node_qa_audit["Scene audit<br/>[audit.mjs]"]
  node_qa_inspection["Browser inspection"]
end

node_agent(("Scene builder"))

node_agent -->|"installs kit"| node_cli
node_cli -->|"copies playbook"| node_playbook
node_agent -->|"follows workflow"| node_playbook
node_playbook -->|"guides scene build"| node_construction
node_playbook -->|"guides model choice"| node_people
node_playbook -->|"specifies camera"| node_orbit
node_playbook -->|"offers hybrid look"| node_pixel_post
node_playbook -->|"offers toon look"| node_toon
node_playbook -->|"prescribes QA"| node_qa_frames
node_playbook -->|"prescribes QA"| node_qa_audit
node_playbook -->|"prescribes QA"| node_qa_inspection
node_pixel_post -->|"uses toon renderer"| node_toon
node_water_main -->|"creates camera"| node_water_camera
node_water_main -->|"creates lighting"| node_water_lighting
node_water_main -->|"creates water"| node_water_surface
node_water_main -->|"creates wake"| node_water_wake
node_water_main -->|"creates splash"| node_water_splash
node_water_main -->|"renders through"| node_post
node_post -->|"reads palette"| node_palette

click node_cli "https://github.com/sloemo01/diorama/blob/main/bin.js"
click node_playbook "https://github.com/sloemo01/diorama/blob/main/README.md"
click node_scene_contract "https://github.com/sloemo01/diorama/blob/main/templates/scene-contract.js"
click node_geometry "https://github.com/sloemo01/diorama/blob/main/templates/geometry.js"
click node_construction "https://github.com/sloemo01/diorama/blob/main/templates/construction-kit.js"
click node_people "https://github.com/sloemo01/diorama/blob/main/templates/peopleModel.js"
click node_street_people "https://github.com/sloemo01/diorama/blob/main/templates/peopleModel-street.js"
click node_poses "https://github.com/sloemo01/diorama/blob/main/templates/poses.js"
click node_transfer "https://github.com/sloemo01/diorama/blob/main/templates/transfer.js"
click node_combat "https://github.com/sloemo01/diorama/blob/main/templates/combat.js"
click node_orbit "https://github.com/sloemo01/diorama/blob/main/templates/orbit.js"
click node_pixel_post "https://github.com/sloemo01/diorama/blob/main/templates/pixel-stroke.js"
click node_toon "https://github.com/sloemo01/diorama/blob/main/templates/stroked-toon.js"
click node_water_main "https://github.com/sloemo01/diorama/blob/main/verify/water/src/main.js"
click node_water_camera "https://github.com/sloemo01/diorama/blob/main/verify/water/src/scene/camera.js"
click node_water_lighting "https://github.com/sloemo01/diorama/blob/main/verify/water/src/scene/lighting.js"
click node_water_surface "https://github.com/sloemo01/diorama/blob/main/verify/water/src/scene/water.js"
click node_water_wake "https://github.com/sloemo01/diorama/blob/main/verify/water/src/scene/wake.js"
click node_water_splash "https://github.com/sloemo01/diorama/blob/main/verify/water/src/scene/splash.js"
click node_post "https://github.com/sloemo01/diorama/blob/main/verify/water/src/core/post.js"
click node_palette "https://github.com/sloemo01/diorama/blob/main/verify/water/src/core/palette.js"
click node_qa_frames "https://github.com/sloemo01/diorama/blob/main/templates/qa/frames.mjs"
click node_qa_audit "https://github.com/sloemo01/diorama/blob/main/templates/qa/audit.mjs"
click node_qa_inspection "https://github.com/sloemo01/diorama/blob/main/templates/qa/inspection-browser.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_cli,node_playbook toneBlue
class node_scene_contract,node_geometry,node_construction,node_people,node_street_people,node_poses,node_transfer,node_combat toneAmber
class node_orbit,node_pixel_post,node_toon toneMint
class node_water_main,node_water_camera,node_water_lighting,node_water_surface,node_water_wake,node_water_splash,node_post,node_palette toneRose
class node_qa_frames,node_qa_audit,node_qa_inspection,node_agent toneIndigo
```

## Components

### Playbook workflow

- [Installer CLI](https://github.com/sloemo01/diorama/blob/main/bin.js): `bin.js`
- [Build playbook](https://github.com/sloemo01/diorama/blob/main/README.md): `README.md`

### Scene toolkit

- [Scene contract](https://github.com/sloemo01/diorama/blob/main/templates/scene-contract.js): `templates/scene-contract.js`
- [Geometry helpers](https://github.com/sloemo01/diorama/blob/main/templates/geometry.js): `templates/geometry.js`
- [Construction kit](https://github.com/sloemo01/diorama/blob/main/templates/construction-kit.js): `templates/construction-kit.js`
- [People models](https://github.com/sloemo01/diorama/blob/main/templates/peopleModel.js): `templates/peopleModel.js`
- [Street people](https://github.com/sloemo01/diorama/blob/main/templates/peopleModel-street.js): `templates/peopleModel-street.js`
- [Pose library](https://github.com/sloemo01/diorama/blob/main/templates/poses.js): `templates/poses.js`
- [Motion transfer](https://github.com/sloemo01/diorama/blob/main/templates/transfer.js): `templates/transfer.js`
- [Combat motion](https://github.com/sloemo01/diorama/blob/main/templates/combat.js): `templates/combat.js`

### Looks and rendering

- [Camera orbit](https://github.com/sloemo01/diorama/blob/main/templates/orbit.js): `templates/orbit.js`
- [Pixel stroke](https://github.com/sloemo01/diorama/blob/main/templates/pixel-stroke.js): `templates/pixel-stroke.js`
- [Stroked toon](https://github.com/sloemo01/diorama/blob/main/templates/stroked-toon.js): `templates/stroked-toon.js`

### Worked scenes

- [Pool scene entry](https://github.com/sloemo01/diorama/blob/main/verify/water/src/main.js): `verify/water/src/main.js`
- [Pool camera](https://github.com/sloemo01/diorama/blob/main/verify/water/src/scene/camera.js): `verify/water/src/scene/camera.js`
- [Pool lighting](https://github.com/sloemo01/diorama/blob/main/verify/water/src/scene/lighting.js): `verify/water/src/scene/lighting.js`
- [Water surface](https://github.com/sloemo01/diorama/blob/main/verify/water/src/scene/water.js): `verify/water/src/scene/water.js`
- [Wake effects](https://github.com/sloemo01/diorama/blob/main/verify/water/src/scene/wake.js): `verify/water/src/scene/wake.js`
- [Splash effects](https://github.com/sloemo01/diorama/blob/main/verify/water/src/scene/splash.js): `verify/water/src/scene/splash.js`
- [Pixel postprocess](https://github.com/sloemo01/diorama/blob/main/verify/water/src/core/post.js): `verify/water/src/core/post.js`
- [Color palette](https://github.com/sloemo01/diorama/blob/main/verify/water/src/core/palette.js): `verify/water/src/core/palette.js`

### Quality checks

- [Frame capture](https://github.com/sloemo01/diorama/blob/main/templates/qa/frames.mjs): `templates/qa/frames.mjs`
- [Scene audit](https://github.com/sloemo01/diorama/blob/main/templates/qa/audit.mjs): `templates/qa/audit.mjs`
- [Browser inspection](https://github.com/sloemo01/diorama/blob/main/templates/qa/inspection-browser.mjs): `templates/qa/inspection-browser.mjs`

### Other components

- **Scene builder**

## Connections

- Scene builder → Installer CLI: installs kit (evidence: `README.md`)
- Installer CLI → Build playbook: copies playbook (evidence: `README.md`)
- Scene builder → Build playbook: follows workflow (evidence: `README.md`)
- Build playbook → Construction kit: guides scene build (evidence: `README.md`)
- Build playbook → People models: guides model choice (evidence: `README.md`)
- Build playbook → Camera orbit: specifies camera (evidence: `README.md`)
- Build playbook → Pixel stroke: offers hybrid look (evidence: `README.md`)
- Build playbook → Stroked toon: offers toon look (evidence: `README.md`)
- Build playbook → Frame capture: prescribes QA (evidence: `README.md`)
- Build playbook → Scene audit: prescribes QA (evidence: `README.md`)
- Build playbook → Browser inspection: prescribes QA (evidence: `README.md`)
- Pixel stroke → Stroked toon: uses toon renderer (evidence: `templates/pixel-stroke.js`)
- Pool scene entry → Pool camera: creates camera (evidence: `verify/water/src/main.js`)
- Pool scene entry → Pool lighting: creates lighting (evidence: `verify/water/src/main.js`)
- Pool scene entry → Water surface: creates water (evidence: `verify/water/src/main.js`)
- Pool scene entry → Wake effects: creates wake (evidence: `verify/water/src/main.js`)
- Pool scene entry → Splash effects: creates splash (evidence: `verify/water/src/main.js`)
- Pool scene entry → Pixel postprocess: renders through (evidence: `verify/water/src/main.js`)
- Pixel postprocess → Color palette: reads palette (evidence: `verify/water/src/core/post.js`)
