# 0xh4ku/snipshelf architecture

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

- Interactive diagram: https://gitdiagram.com/0xh4ku/snipshelf
- Repository: https://github.com/0xh4ku/snipshelf

## Overview

SnipShelf is a native macOS visual-reference shelf. Its main workflow starts with screen capture or image import, refines an image into a cutout, then saves and organizes clips for search, preview, export, and floating references. PaletteKit adds subject-aware color analysis and configurable palettes. The tree and excerpts support the main entry points and analysis links; wiring for some storage, masking, and window details is only partially sampled, so those relations are omitted where uncertain.

Main entry points: [`Sources/SnipShelf/AppController.swift`](https://github.com/0xh4ku/snipshelf/blob/main/Sources/SnipShelf/AppController.swift) (App controller), [`Sources/PaletteKit/PaletteModel.swift`](https://github.com/0xh4ku/snipshelf/blob/main/Sources/PaletteKit/PaletteModel.swift) (Palette model), [`Sources/SnipShelf/CaptureCanvas.swift`](https://github.com/0xh4ku/snipshelf/blob/main/Sources/SnipShelf/CaptureCanvas.swift) (Capture canvas), [`Sources/SnipShelf/ShelfStore.swift`](https://github.com/0xh4ku/snipshelf/blob/main/Sources/SnipShelf/ShelfStore.swift) (Shelf store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture and Cutouts"]
  node_capturecanvas["Capture canvas"]
  node_mask["Subject masking<br/>[SubjectMask.swift]"]
  node_imagecore["Image processing<br/>[ImageCore.swift]"]
end

subgraph group_shelf["Shelf and Library"]
  node_app["App controller"]
  node_preview["Clip preview<br/>[PreviewView.swift]"]
  node_store[("Shelf store<br/>[ShelfStore.swift]")]
  node_collection["Shelf collection"]
  node_library["Library view<br/>[LibraryView.swift]"]
  node_backup["Backup and recovery<br/>[ShelfBackup.swift]"]
end

subgraph group_references["References"]
  node_referencewindow["Reference windows"]
  node_referenceview["Reference display"]
end

subgraph group_palette["Color Analysis"]
  node_paletteview["Clip palette"]
  node_palettemodel["Palette model<br/>[PaletteModel.swift]"]
  node_analysis["Palette analysis"]
  node_settings["Palette settings"]
  node_strip["Palette strip"]
  node_preferences[("Saved preferences")]
end

node_user(("Mac user"))
node_screen["Screen content"]
node_imagefiles["Image files"]

node_user -->|"starts actions"| node_app
node_app -->|"opens capture"| node_capturecanvas
node_screen -->|"captured from"| node_capturecanvas
node_user -->|"chooses images"| node_imagefiles
node_app -->|"imports"| node_imagefiles
node_capturecanvas -->|"refines selection"| node_mask
node_capturecanvas -->|"processes image"| node_imagecore
node_app -->|"imports and saves"| node_store
node_app -->|"presents shelf"| node_collection
node_collection -->|"reads clips"| node_store
node_app -->|"opens preview"| node_preview
node_preview -->|"loads image"| node_imagecore
node_app -->|"opens references"| node_referencewindow
node_referencewindow -->|"hosts view"| node_referenceview
node_referenceview -->|"reads clip data"| node_store
node_app -->|"initiates recovery"| node_backup
node_app -->|"requests analysis"| node_palettemodel
node_paletteview -->|"presents colors"| node_palettemodel
node_palettemodel -->|"analyzes image"| node_analysis
node_analysis -->|"returns palette"| node_palettemodel
node_paletteview -->|"renders swatches"| node_strip
node_settings -->|"updates options"| node_palettemodel
node_palettemodel -->|"loads and saves"| node_preferences
node_strip -->|"copies HEX"| node_user

click node_app "https://github.com/0xh4ku/snipshelf/blob/main/Sources/SnipShelf/AppController.swift"
click node_capturecanvas "https://github.com/0xh4ku/snipshelf/blob/main/Sources/SnipShelf/CaptureCanvas.swift"
click node_mask "https://github.com/0xh4ku/snipshelf/blob/main/Sources/SnipShelf/SubjectMask.swift"
click node_imagecore "https://github.com/0xh4ku/snipshelf/blob/main/Sources/SnipShelf/ImageCore.swift"
click node_preview "https://github.com/0xh4ku/snipshelf/blob/main/Sources/SnipShelf/PreviewView.swift"
click node_store "https://github.com/0xh4ku/snipshelf/blob/main/Sources/SnipShelf/ShelfStore.swift"
click node_collection "https://github.com/0xh4ku/snipshelf/blob/main/Sources/SnipShelf/ShelfCollection.swift"
click node_library "https://github.com/0xh4ku/snipshelf/blob/main/Sources/SnipShelf/LibraryView.swift"
click node_backup "https://github.com/0xh4ku/snipshelf/blob/main/Sources/SnipShelf/ShelfBackup.swift"
click node_referencewindow "https://github.com/0xh4ku/snipshelf/blob/main/Sources/SnipShelf/ReferenceWindow.swift"
click node_referenceview "https://github.com/0xh4ku/snipshelf/blob/main/Sources/SnipShelf/ReferenceView.swift"
click node_paletteview "https://github.com/0xh4ku/snipshelf/blob/main/Sources/SnipShelf/ClipPaletteView.swift"
click node_palettemodel "https://github.com/0xh4ku/snipshelf/blob/main/Sources/PaletteKit/PaletteModel.swift"
click node_analysis "https://github.com/0xh4ku/snipshelf/blob/main/Sources/PaletteKit/PaletteAnalysis.swift"
click node_settings "https://github.com/0xh4ku/snipshelf/blob/main/Sources/PaletteKit/PaletteSettingsView.swift"
click node_strip "https://github.com/0xh4ku/snipshelf/blob/main/Sources/PaletteKit/PaletteStripView.swift"
click node_preferences "https://github.com/0xh4ku/snipshelf/blob/main/Sources/PaletteKit/PaletteDefaults.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_capturecanvas,node_mask,node_imagecore,node_user,node_screen toneBlue
class node_app,node_preview,node_store,node_collection,node_library,node_backup toneAmber
class node_referencewindow,node_referenceview toneMint
class node_paletteview,node_palettemodel,node_analysis,node_settings,node_strip,node_preferences toneRose
class node_imagefiles toneIndigo
```

## Components

### Capture and Cutouts

- [Capture canvas](https://github.com/0xh4ku/snipshelf/blob/main/Sources/SnipShelf/CaptureCanvas.swift): `Sources/SnipShelf/CaptureCanvas.swift`
- [Subject masking](https://github.com/0xh4ku/snipshelf/blob/main/Sources/SnipShelf/SubjectMask.swift): `Sources/SnipShelf/SubjectMask.swift`
- [Image processing](https://github.com/0xh4ku/snipshelf/blob/main/Sources/SnipShelf/ImageCore.swift): `Sources/SnipShelf/ImageCore.swift`

### Shelf and Library

- [App controller](https://github.com/0xh4ku/snipshelf/blob/main/Sources/SnipShelf/AppController.swift): `Sources/SnipShelf/AppController.swift`
- [Clip preview](https://github.com/0xh4ku/snipshelf/blob/main/Sources/SnipShelf/PreviewView.swift): `Sources/SnipShelf/PreviewView.swift`
- [Shelf store](https://github.com/0xh4ku/snipshelf/blob/main/Sources/SnipShelf/ShelfStore.swift): `Sources/SnipShelf/ShelfStore.swift`
- [Shelf collection](https://github.com/0xh4ku/snipshelf/blob/main/Sources/SnipShelf/ShelfCollection.swift): `Sources/SnipShelf/ShelfCollection.swift`
- [Library view](https://github.com/0xh4ku/snipshelf/blob/main/Sources/SnipShelf/LibraryView.swift): `Sources/SnipShelf/LibraryView.swift`
- [Backup and recovery](https://github.com/0xh4ku/snipshelf/blob/main/Sources/SnipShelf/ShelfBackup.swift): `Sources/SnipShelf/ShelfBackup.swift`

### References

- [Reference windows](https://github.com/0xh4ku/snipshelf/blob/main/Sources/SnipShelf/ReferenceWindow.swift): `Sources/SnipShelf/ReferenceWindow.swift`
- [Reference display](https://github.com/0xh4ku/snipshelf/blob/main/Sources/SnipShelf/ReferenceView.swift): `Sources/SnipShelf/ReferenceView.swift`

### Color Analysis

- [Clip palette](https://github.com/0xh4ku/snipshelf/blob/main/Sources/SnipShelf/ClipPaletteView.swift): `Sources/SnipShelf/ClipPaletteView.swift`
- [Palette model](https://github.com/0xh4ku/snipshelf/blob/main/Sources/PaletteKit/PaletteModel.swift): `Sources/PaletteKit/PaletteModel.swift`
- [Palette analysis](https://github.com/0xh4ku/snipshelf/blob/main/Sources/PaletteKit/PaletteAnalysis.swift): `Sources/PaletteKit/PaletteAnalysis.swift`
- [Palette settings](https://github.com/0xh4ku/snipshelf/blob/main/Sources/PaletteKit/PaletteSettingsView.swift): `Sources/PaletteKit/PaletteSettingsView.swift`
- [Palette strip](https://github.com/0xh4ku/snipshelf/blob/main/Sources/PaletteKit/PaletteStripView.swift): `Sources/PaletteKit/PaletteStripView.swift`
- [Saved preferences](https://github.com/0xh4ku/snipshelf/blob/main/Sources/PaletteKit/PaletteDefaults.swift): `Sources/PaletteKit/PaletteDefaults.swift`

### Other components

- **Mac user**
- **Screen content**
- **Image files**

## Connections

- Mac user → App controller: starts actions
- App controller → Capture canvas: opens capture
- Screen content → Capture canvas: captured from
- Mac user → Image files: chooses images
- App controller → Image files: imports
- Capture canvas → Subject masking: refines selection
- Capture canvas → Image processing: processes image
- App controller → Shelf store: imports and saves
- App controller → Shelf collection: presents shelf
- Shelf collection → Shelf store: reads clips
- App controller → Clip preview: opens preview
- Clip preview → Image processing: loads image
- App controller → Reference windows: opens references
- Reference windows → Reference display: hosts view
- Reference display → Shelf store: reads clip data
- App controller → Backup and recovery: initiates recovery
- App controller → Palette model: requests analysis
- Clip palette → Palette model: presents colors
- Palette model → Palette analysis: analyzes image
- Palette analysis → Palette model: returns palette
- Clip palette → Palette strip: renders swatches
- Palette settings → Palette model: updates options
- Palette model → Saved preferences: loads and saves
- Palette strip → Mac user: copies HEX