# elliotttate/spatialslideshow architecture

> Architecture diagram of the GitHub repository elliotttate/spatialslideshow, 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/elliotttate/spatialslideshow
- Repository: https://github.com/elliotttate/spatialslideshow

## Overview

Spatial Slideshow is a native Mac app that turns Photos-album or local-image selections into moving 3D scenes or video clips. The principal workflow selects sources, prepares them (including optional edge expansion), then queues and plays prepared items; playback can also render cached scenes live. The graph preserves documented model setup, music, and screen-saver capabilities. Several runtime modules are unsampled, so their internal call relationships are omitted rather than inferred.

Main entry points: [`Sources/SlideshowApp.swift`](https://github.com/elliotttate/spatialslideshow/blob/main/Sources/SlideshowApp.swift) (Slideshow App), [`Sources/PlaybackPipeline.swift`](https://github.com/elliotttate/spatialslideshow/blob/main/Sources/PlaybackPipeline.swift) (Preparation Pipeline), [`Sources/PhotoExpansion.swift`](https://github.com/elliotttate/spatialslideshow/blob/main/Sources/PhotoExpansion.swift) (Photo Expansion), [`Sources/AlbumBrowser.swift`](https://github.com/elliotttate/spatialslideshow/blob/main/Sources/AlbumBrowser.swift) (Album Browser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and Playback"]
  node_app["Slideshow App<br/>[SlideshowApp.swift]"]
  node_albums["Album Browser<br/>[AlbumBrowser.swift]"]
  node_options["Playback Options"]
  node_playback["Continuous Playback"]
  node_live["Live Scene Surface"]
  node_music["Music Playback"]
end

subgraph group_prepare["Preparation and Rendering"]
  node_pipeline["Preparation Pipeline"]
  node_queue["Album Preparation Queue"]
  node_scene["Scene Generation"]
  node_helpers["Helper Process"]
end

subgraph group_models["Models and Expansion"]
  node_expansion["Photo Expansion"]
  node_apple["Apple Expansion<br/>[ExpandPhoto.swift]"]
  node_drawthings["Draw Things Engine"]
  node_klein["Klein Engine"]
  node_runtime["Model Runtime Setup"]
end

subgraph group_persistence["Caches and Destinations"]
  node_clips[("Clip Cache")]
  node_scenes[("Scene Cache<br/>[SceneCache.swift]")]
  node_video[("Video Cache")]
  node_screensaver["Screen Saver"]
end

node_user(("Viewer"))
node_photos["Apple Photos"]

node_user -->|"starts slideshow"| node_app
node_app -->|"browses albums"| node_albums
node_albums -->|"loads assets"| node_photos
node_app -->|"configures playback"| node_options
node_app -->|"prepares items"| node_queue
node_app -->|"requests renders"| node_pipeline
node_pipeline -->|"expands input"| node_expansion
node_expansion -->|"runs backend"| node_apple
node_expansion -->|"runs backend"| node_drawthings
node_expansion -->|"runs backend"| node_klein
node_expansion -->|"checks runtime"| node_runtime
node_pipeline -->|"generates scene"| node_scene
node_pipeline -->|"uses clip cache"| node_clips
node_pipeline -->|"uses scene cache"| node_scenes
node_pipeline -->|"uses video cache"| node_video
node_pipeline -->|"runs helpers"| node_helpers
node_app -->|"feeds prepared items"| node_playback
node_playback -->|"renders live scenes"| node_live
node_app -->|"controls music"| node_music
node_app -->|"manages screen saver"| node_screensaver
node_screensaver -->|"reads scene cache"| node_scenes
node_user -->|"sets up models"| node_runtime

click node_app "https://github.com/elliotttate/spatialslideshow/blob/main/Sources/SlideshowApp.swift"
click node_albums "https://github.com/elliotttate/spatialslideshow/blob/main/Sources/AlbumBrowser.swift"
click node_options "https://github.com/elliotttate/spatialslideshow/blob/main/Sources/SlideshowOptions.swift"
click node_pipeline "https://github.com/elliotttate/spatialslideshow/blob/main/Sources/PlaybackPipeline.swift"
click node_queue "https://github.com/elliotttate/spatialslideshow/blob/main/Sources/AlbumPreparationQueue.swift"
click node_expansion "https://github.com/elliotttate/spatialslideshow/blob/main/Sources/PhotoExpansion.swift"
click node_apple "https://github.com/elliotttate/spatialslideshow/blob/main/Sources/ExpandPhoto.swift"
click node_drawthings "https://github.com/elliotttate/spatialslideshow/blob/main/Sources/ExpandPhotoDrawThings.py"
click node_klein "https://github.com/elliotttate/spatialslideshow/blob/main/Sources/ExpandPhotoKlein.py"
click node_scene "https://github.com/elliotttate/spatialslideshow/blob/main/Sources/GenerateScene.swift"
click node_runtime "https://github.com/elliotttate/spatialslideshow/blob/main/Sources/RuntimeInstaller.swift"
click node_helpers "https://github.com/elliotttate/spatialslideshow/blob/main/Sources/HelperProcess.swift"
click node_playback "https://github.com/elliotttate/spatialslideshow/blob/main/Sources/ContinuousPlayback.swift"
click node_live "https://github.com/elliotttate/spatialslideshow/blob/main/Sources/LivePlaybackSurface.swift"
click node_clips "https://github.com/elliotttate/spatialslideshow/blob/main/Sources/ClipCacheCatalog.swift"
click node_scenes "https://github.com/elliotttate/spatialslideshow/blob/main/Sources/SceneCache.swift"
click node_video "https://github.com/elliotttate/spatialslideshow/blob/main/Sources/VideoClipCache.swift"
click node_music "https://github.com/elliotttate/spatialslideshow/blob/main/Sources/MusicPlayback.swift"
click node_screensaver "https://github.com/elliotttate/spatialslideshow/blob/main/Sources/ScreenSaverController.swift"

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_app,node_albums,node_options,node_playback,node_live,node_music,node_user toneBlue
class node_pipeline,node_queue,node_scene,node_helpers toneAmber
class node_expansion,node_apple,node_drawthings,node_klein,node_runtime toneMint
class node_clips,node_scenes,node_video,node_screensaver toneRose
class node_photos toneIndigo
```

## Components

### App and Playback

- [Slideshow App](https://github.com/elliotttate/spatialslideshow/blob/main/Sources/SlideshowApp.swift): `Sources/SlideshowApp.swift`
- [Album Browser](https://github.com/elliotttate/spatialslideshow/blob/main/Sources/AlbumBrowser.swift): `Sources/AlbumBrowser.swift`
- [Playback Options](https://github.com/elliotttate/spatialslideshow/blob/main/Sources/SlideshowOptions.swift): `Sources/SlideshowOptions.swift`
- [Continuous Playback](https://github.com/elliotttate/spatialslideshow/blob/main/Sources/ContinuousPlayback.swift): `Sources/ContinuousPlayback.swift`
- [Live Scene Surface](https://github.com/elliotttate/spatialslideshow/blob/main/Sources/LivePlaybackSurface.swift): `Sources/LivePlaybackSurface.swift`
- [Music Playback](https://github.com/elliotttate/spatialslideshow/blob/main/Sources/MusicPlayback.swift): `Sources/MusicPlayback.swift`

### Preparation and Rendering

- [Preparation Pipeline](https://github.com/elliotttate/spatialslideshow/blob/main/Sources/PlaybackPipeline.swift): `Sources/PlaybackPipeline.swift`
- [Album Preparation Queue](https://github.com/elliotttate/spatialslideshow/blob/main/Sources/AlbumPreparationQueue.swift): `Sources/AlbumPreparationQueue.swift`
- [Scene Generation](https://github.com/elliotttate/spatialslideshow/blob/main/Sources/GenerateScene.swift): `Sources/GenerateScene.swift`
- [Helper Process](https://github.com/elliotttate/spatialslideshow/blob/main/Sources/HelperProcess.swift): `Sources/HelperProcess.swift`

### Models and Expansion

- [Photo Expansion](https://github.com/elliotttate/spatialslideshow/blob/main/Sources/PhotoExpansion.swift): `Sources/PhotoExpansion.swift`
- [Apple Expansion](https://github.com/elliotttate/spatialslideshow/blob/main/Sources/ExpandPhoto.swift): `Sources/ExpandPhoto.swift`
- [Draw Things Engine](https://github.com/elliotttate/spatialslideshow/blob/main/Sources/ExpandPhotoDrawThings.py): `Sources/ExpandPhotoDrawThings.py`
- [Klein Engine](https://github.com/elliotttate/spatialslideshow/blob/main/Sources/ExpandPhotoKlein.py): `Sources/ExpandPhotoKlein.py`
- [Model Runtime Setup](https://github.com/elliotttate/spatialslideshow/blob/main/Sources/RuntimeInstaller.swift): `Sources/RuntimeInstaller.swift`

### Caches and Destinations

- [Clip Cache](https://github.com/elliotttate/spatialslideshow/blob/main/Sources/ClipCacheCatalog.swift): `Sources/ClipCacheCatalog.swift`
- [Scene Cache](https://github.com/elliotttate/spatialslideshow/blob/main/Sources/SceneCache.swift): `Sources/SceneCache.swift`
- [Video Cache](https://github.com/elliotttate/spatialslideshow/blob/main/Sources/VideoClipCache.swift): `Sources/VideoClipCache.swift`
- [Screen Saver](https://github.com/elliotttate/spatialslideshow/blob/main/Sources/ScreenSaverController.swift): `Sources/ScreenSaverController.swift`

### Other components

- **Viewer**
- **Apple Photos**

## Connections

- Viewer → Slideshow App: starts slideshow
- Slideshow App → Album Browser: browses albums (evidence: `Sources/SlideshowApp.swift`)
- Album Browser → Apple Photos: loads assets
- Slideshow App → Playback Options: configures playback (evidence: `Sources/SlideshowApp.swift`)
- Slideshow App → Album Preparation Queue: prepares items (evidence: `Sources/SlideshowApp.swift`)
- Slideshow App → Preparation Pipeline: requests renders (evidence: `Sources/SlideshowApp.swift`)
- Preparation Pipeline → Photo Expansion: expands input (evidence: `Sources/PlaybackPipeline.swift`)
- Photo Expansion → Apple Expansion: runs backend (evidence: `Sources/PhotoExpansion.swift`)
- Photo Expansion → Draw Things Engine: runs backend (evidence: `Sources/PhotoExpansion.swift`)
- Photo Expansion → Klein Engine: runs backend (evidence: `Sources/PhotoExpansion.swift`)
- Photo Expansion → Model Runtime Setup: checks runtime (evidence: `Sources/PhotoExpansion.swift`)
- Preparation Pipeline → Scene Generation: generates scene (evidence: `Sources/PlaybackPipeline.swift`)
- Preparation Pipeline → Clip Cache: uses clip cache (evidence: `Sources/PlaybackPipeline.swift`)
- Preparation Pipeline → Scene Cache: uses scene cache (evidence: `Sources/PlaybackPipeline.swift`)
- Preparation Pipeline → Video Cache: uses video cache (evidence: `Sources/PlaybackPipeline.swift`)
- Preparation Pipeline → Helper Process: runs helpers (evidence: `Sources/PlaybackPipeline.swift`)
- Slideshow App → Continuous Playback: feeds prepared items (evidence: `Sources/SlideshowApp.swift`)
- Continuous Playback → Live Scene Surface: renders live scenes (evidence: `Sources/SlideshowPlayerView.swift`)
- Slideshow App → Music Playback: controls music (evidence: `Sources/SlideshowApp.swift`)
- Slideshow App → Screen Saver: manages screen saver (evidence: `Sources/SlideshowApp.swift`)
- Screen Saver → Scene Cache: reads scene cache
- Viewer → Model Runtime Setup: sets up models
