# thelordofdino4/steam-backup-label-studio architecture

> Architecture diagram of the GitHub repository thelordofdino4/steam-backup-label-studio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thelordofdino4/steam-backup-label-studio
- Repository: https://github.com/thelordofdino4/steam-backup-label-studio

## Overview

1. **Overall shape**
   - This is a **cross-platform desktop app** built with **Tauri** for the shell/native integration, **React + TypeScript** for the UI, and **Rust** in `src-tauri` for filesystem/platform commands.
   - The current product surface is the **disc-label editor**; case-insert work is present in the codebase as a parallel subsystem and future expansion path.

2. **Frontend/backend boundary**
   - The UI lives under `src/`, while native capabilities live under `src-tauri/`.
   - Rust commands are grouped by concern: file operations, local image access, Steam/local Steam helpers, official-site lookup, and open-folder behavior. The frontend calls these through Tauri rather than talking to the OS directly.

3. **App composition**
   - `src/main.tsx` and `src/app/App.tsx` boot the app shell.
   - The main UI is split into **home**, **sidebar controls**, and **live preview** areas. `CaseInsertEditorShell` and `EditorPanel` show the app is organized around a shell that combines control panels with a visual workspace.

4. **Primary domain model**
   - The project model is centralized in `src/project/`.
   - This layer owns project schema, normalization, restore/snapshot logic, routing, and per-feature project adapters for metadata, artwork, marks, title artwork, and disc/case-specific state.
   - Saved projects are plain JSON `.sbls.json` files, with embedded asset data where needed and explicit provenance/status fields.

5. **Current alpha surface: disc editor**
   - The disc editor is the finished alpha-capable surface.
   - Its domain modules are split into **disc geometry**, **disc text**, **templates/layout**, **render/export**, and **preview/editor interaction**. That separation is important: the visual preview, export, and saved state all consume the same core project data and layout rules.

6. **Future/parallel surface: case insert**
   - `src/caseInsert/` contains a parallel architecture for jewel-case style surfaces: template surfaces, branding, spine text, title artwork, Steam banner placement, guide options, and export settings.
   - `src/components/caseInsert/` mirrors that domain with dedicated controls and shell components, indicating the app is designed for multiple packaging surfaces rather than only disc labels.

7. **Artwork and asset pipeline**
   - Artwork enters the system through several sources: **local uploads**, **Steam metadata/artwork**, **Steam screenshots**, **local Steam screenshots**, and **web candidate discovery**.
   - Core image utilities live in `src/image/`, `src/local/`, `src/steam/`, and `src/utils/`.
   - Built-in assets are routed through `src/assets/assetManifest.ts`, with domain-specific asset folders for logos, marks, badges, placeholders, and other reusable artwork.

8. **Steam integration**
   - `src/steam/` is the domain layer for external Steam data: metadata candidates, logo candidates, artwork import, platform marks, title artwork import, and auto-apply logic.
   - The app does not treat Steam as a single monolithic import; it decomposes Steam into metadata, candidate ranking, artwork selection, and optional mark inference.

9. **Preview and export pipeline**
   - Live preview components live under `src/components/preview/`, while export drawing logic is in `src/export/`.
   - The architecture intentionally keeps **preview/export parity**: shared layer-order policy, shared layout math, and matching render models are used so what the user sees is what gets exported.
   - Export produces **print-ready PNGs** and includes **preflight checks** for warnings, dimensions, and readability risks.

10. **Layout, geometry, and rendering**
   - `src/layout/` contains the physical and visual layout contracts: safe zones, guide layouts, template geometry, text occupied regions, and preset layouts.
   - `src/render/` maps domain features into render models, and `src/export/draw*.ts` files turn those models into canvas output.
   - This split makes geometry a first-class dependency rather than an incidental UI concern.

11. **Text system**
   - Text is its own subsystem across `src/text/`, `src/discText/`, and the preview inline editor components.
   - It supports both straight and curved disc text, styling, layout, wrapping, selection/editing, and avoidance against other visual elements.
   - The inline preview editor has explicit contract and smoke-test coverage, which suggests this area is treated as a fragile boundary.

12. **User interaction and state hooks**
   - Drag/selection behavior is isolated in `src/interaction/`.
   - Feature-specific React hooks in `src/hooks/` sync editor state, discover assets, and bridge UI controls to project state.
   - The control flow is: user input in sidebar or preview → hook/state update → normalized project model → preview re-render/export model update.

13. **UI structure and styling**
   - The UI is partitioned into reusable sidebar panels and feature-specific controls under `src/components/sidebar/` and `src/components/editor/`.
   - Styling is organized as layered CSS files in `src/styles/`, matching the app’s layered preview/editor structure rather than a single monolithic stylesheet.

14. **Quality gates and diagnostics**
   - The repo is test-heavy: many domain modules have adjacent tests, and there are diagnostics for project parity and text-editor contracts.
   - Scripts like `check-cycles.mjs` and `text-editor-smoke.mjs`, plus the GitHub CI workflow, indicate that architectural invariants such as import cycles, preview/text contracts, and saved-project parity are treated as build-time concerns.

15. **Native/system responsibilities**
   - The Rust side is deliberately small and focused: file access, folder opening, and Steam/local-image related commands.
   - The UI owns most app logic; the native layer exists to cross the desktop boundary safely and consistently.

16. **Diagram-friendly summary**
   - A good architecture diagram should show three major flows:
     - **Project/data flow:** file load/save → normalize/restore project state → editor hooks/components.
     - **Asset flow:** Steam/local/web/user assets → discovery/import/ranking → project-owned asset state → preview/export.
     - **Render flow:** project state + layout/geometry → preview layers and export drawing → PNG output with preflight checks.

Main entry points: [`src/project/projectSchema.ts`](https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/project/projectSchema.ts) (Project state), [`src/app/App.tsx`](https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/app/App.tsx) (App shell), [`src/assets/assetManifest.ts`](https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/assets/assetManifest.ts) (Artwork assets), [`src/components/preview/DiscPreview.tsx`](https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/components/preview/DiscPreview.tsx) (Preview shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["App Shell"]
  node_node_main["App entry<br/>React bootstrap<br/>[main.tsx]"]
  node_node_app["App shell<br/>Top-level React<br/>[App.tsx]"]
  node_node_home["Home screen<br/>UI surface<br/>[HomeScreen.tsx]"]
  node_node_sidebar["Sidebar panels<br/>Controls UI<br/>[ProjectPanel.tsx]"]
  node_node_preview["Preview shell<br/>Visual workspace<br/>[DiscPreview.tsx]"]
end

subgraph group_group_project["Project Model"]
  node_node_project[("Project state<br/>Saved-model core<br/>[projectSchema.ts]")]
  node_node_project_restore["Restore/snapshot<br/>State lifecycle"]
  node_node_project_adapters["Feature adapters<br/>Project adapters"]
end

subgraph group_group_disc["Disc Surface"]
  node_node_disc_geom{{"Disc geometry<br/>Layout math<br/>[geometry.ts]"}}
  node_node_disc_text["Disc text<br/>Text subsystem<br/>[index.ts]"]
  node_node_disc_templates["Disc templates<br/>Template/layout<br/>[discTemplates.ts]"]
  node_node_disc_editor["Disc editor<br/>Interaction hooks"]
end

subgraph group_group_case["Case Insert"]
  node_node_case_shell["Case shell<br/>Parallel surface"]
  node_node_case_domain[("Case domain<br/>Case insert model<br/>[types.ts]")]
  node_node_case_preview["Case preview"]
end

subgraph group_group_assets["Assets & Import"]
  node_node_assets["Artwork assets<br/>Asset pipeline<br/>[assetManifest.ts]"]
  node_node_steam["Steam import<br/>External data"]
  node_node_local["Local sources<br/>Local import<br/>[localArtwork.ts]"]
end

subgraph group_group_render["Render & Export"]
  node_node_layout{{"Layout engine<br/>Geometry/layout"}}
  node_node_render["Render models<br/>Preview/render<br/>[artworkFrame.ts]"]
  node_node_export["Export pipeline<br/>PNG export<br/>[exportPng.ts]"]
end

subgraph group_group_native["Native Boundary"]
  node_node_tauri["Tauri commands<br/>Native bridge<br/>[mod.rs]"]
  node_node_files["File commands<br/>Rust fs<br/>[files.rs]"]
end

node_node_main -->|"boots"| node_node_app
node_node_app -->|"shows"| node_node_home
node_node_app -->|"composes"| node_node_sidebar
node_node_app -->|"composes"| node_node_preview
node_node_app -->|"switches to"| node_node_case_shell
node_node_app -->|"loads state"| node_node_project
node_node_project -->|"restores"| node_node_project_restore
node_node_project -->|"adapts"| node_node_project_adapters
node_node_project -->|"references assets"| node_node_assets
node_node_disc_editor -->|"updates"| node_node_project
node_node_disc_editor -->|"controls"| node_node_disc_text
node_node_disc_editor -->|"selects"| node_node_disc_templates
node_node_disc_text -->|"uses"| node_node_layout
node_node_disc_templates -->|"uses"| node_node_layout
node_node_preview -->|"renders via"| node_node_render
node_node_render -->|"feeds"| node_node_export
node_node_export -->|"uses"| node_node_layout
node_node_export -->|"reads"| node_node_project
node_node_case_shell -->|"drives"| node_node_case_domain
node_node_case_shell -->|"drives"| node_node_case_preview
node_node_case_domain -->|"uses"| node_node_layout
node_node_assets -->|"imports from"| node_node_steam
node_node_assets -->|"imports from"| node_node_local
node_node_assets -->|"stores into"| node_node_project
node_node_preview -->|"shows"| node_node_assets
node_node_tauri -->|"exposes"| node_node_files
node_node_steam -->|"calls"| node_node_tauri
node_node_local -->|"calls"| node_node_tauri
node_node_sidebar -->|"edits"| node_node_project
node_node_preview -->|"interaction"| node_node_disc_editor

click node_node_main "https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/main.tsx"
click node_node_app "https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/app/App.tsx"
click node_node_home "https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/components/home/HomeScreen.tsx"
click node_node_sidebar "https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/components/sidebar/ProjectPanel.tsx"
click node_node_preview "https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/components/preview/DiscPreview.tsx"
click node_node_project "https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/project/projectSchema.ts"
click node_node_project_restore "https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/project/createProjectSnapshot.ts"
click node_node_project_adapters "https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/project/caseInsertProjectAdapters.ts"
click node_node_disc_geom "https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/disc/geometry.ts"
click node_node_disc_text "https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/discText/index.ts"
click node_node_disc_templates "https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/templates/discTemplates.ts"
click node_node_disc_editor "https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/hooks/useDiscTextState.ts"
click node_node_case_shell "https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/components/caseInsert/CaseInsertEditorShell.tsx"
click node_node_case_domain "https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/caseInsert/types.ts"
click node_node_case_preview "https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/components/preview/CaseInsertPreview.tsx"
click node_node_assets "https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/assets/assetManifest.ts"
click node_node_steam "https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/steam/steamMetadataCandidates.ts"
click node_node_local "https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/local/localArtwork.ts"
click node_node_layout "https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/layout/discElementSafeZone.ts"
click node_node_render "https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/render/artworkFrame.ts"
click node_node_export "https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/export/exportPng.ts"
click node_node_tauri "https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src-tauri/src/commands/mod.rs"
click node_node_files "https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src-tauri/src/commands/files.rs"

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_node_main,node_node_app,node_node_home,node_node_sidebar,node_node_preview,node_node_tauri,node_node_files toneBlue
class node_node_project,node_node_project_restore,node_node_project_adapters toneAmber
class node_node_disc_geom,node_node_disc_text,node_node_disc_templates,node_node_disc_editor toneMint
class node_node_case_shell,node_node_case_domain,node_node_case_preview toneRose
class node_node_assets,node_node_steam,node_node_local toneIndigo
class node_node_layout,node_node_render,node_node_export toneTeal
```

## Components

### App Shell

React entrypoints, top-level composition, and shared UI surfaces.

- [App entry](https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/main.tsx): React bootstrap · Starts the desktop UI and mounts the app shell. · `src/main.tsx`
- [App shell](https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/app/App.tsx): Top-level React · Routes the main workspace and coordinates home/editor surfaces. · `src/app/App.tsx`
- [Home screen](https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/components/home/HomeScreen.tsx): UI surface · Landing surface and navigation into the editor workflow. · `src/components/home/HomeScreen.tsx`
- [Sidebar panels](https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/components/sidebar/ProjectPanel.tsx): Controls UI · Reusable sidebar panels for project, metadata, artwork, branding, text, templates, and export controls. · `src/components/sidebar/ProjectPanel.tsx`
- [Preview shell](https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/components/preview/DiscPreview.tsx): Visual workspace · Live preview components for disc and case-insert surfaces plus overlays and inline editing. · `src/components/preview/DiscPreview.tsx`

### Project Model

Canonical saved state, normalization, routing, and project feature adapters.

- [Project state](https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/project/projectSchema.ts): Saved-model core · Canonical project schema, normalization, restore/snapshot logic, routing, and feature adapters. · `src/project/projectSchema.ts`
- [Restore/snapshot](https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/project/createProjectSnapshot.ts): State lifecycle · Creates snapshots and restores normalized project state from saved files. · `src/project/createProjectSnapshot.ts`
- [Feature adapters](https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/project/caseInsertProjectAdapters.ts): Project adapters · Per-feature project state for metadata, artwork, logos, marks, rating, technical marks, title artwork, and case insert. · `src/project/caseInsertProjectAdapters.ts`

### Disc Surface

Disc-label geometry, text, templates, preview, and editor interactions.

- [Disc geometry](https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/disc/geometry.ts): Layout math · Disc-specific physical geometry and safe-zone constraints. · `src/disc/geometry.ts`
- [Disc text](https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/discText/index.ts): Text subsystem · Curved and straight disc text layout, avoidance, styles, and inline editing support. · `src/discText/index.ts`
- [Disc templates](https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/templates/discTemplates.ts): Template/layout · Disc template defaults and layout contracts for the current alpha surface. · `src/templates/discTemplates.ts`
- [Disc editor](https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/hooks/useDiscTextState.ts): Interaction hooks · Disc preview pointer drag, text state, template state, and preview sizing hooks. · `src/hooks/useDiscTextState.ts`

### Case Insert

Parallel jewel-case surface architecture for future expansion.

- [Case shell](https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/components/caseInsert/CaseInsertEditorShell.tsx): Parallel surface · Case-insert editor shell and workflow organization for jewel-case surfaces. · `src/components/caseInsert/CaseInsertEditorShell.tsx`
- [Case domain](https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/caseInsert/types.ts): Case insert model · Case-insert templates, text, branding, spine, banner, title artwork, and export settings. · `src/caseInsert/types.ts`
- [Case preview](https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/components/preview/CaseInsertPreview.tsx): Case preview · Case-insert preview layers, guides, and inline text editing controls. · `src/components/preview/CaseInsertPreview.tsx`

### Assets & Import

Artwork discovery, Steam integration, local image handling, and built-in assets.

- [Artwork assets](https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/assets/assetManifest.ts): Asset pipeline · Local uploads, built-in assets, image utilities, and asset manifests. · `src/assets/assetManifest.ts`
- [Steam import](https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/steam/steamMetadataCandidates.ts): External data · Steam metadata, logo candidates, artwork import, platform marks, and auto-apply logic. · `src/steam/steamMetadataCandidates.ts`
- [Local sources](https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/local/localArtwork.ts): Local import · Local artwork and Steam screenshot discovery/thumbnails from the filesystem. · `src/local/localArtwork.ts`

### Render & Export

Preview/render models, canvas drawing, export PNG generation, and checks.

- [Layout engine](https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/layout/discElementSafeZone.ts): Geometry/layout · Shared safe zones, occupied regions, guide layouts, and physical placement rules. · `src/layout/discElementSafeZone.ts`
- [Render models](https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/render/artworkFrame.ts): Preview/render · Maps project state into render models for layers and export drawing. · `src/render/artworkFrame.ts`
- [Export pipeline](https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src/export/exportPng.ts): PNG export · Canvas drawing, preview/export parity, guides, preflight checks, and print-ready PNG output. · `src/export/exportPng.ts`

### Native Boundary

Tauri/Rust commands for filesystem and platform-specific access.

- [Tauri commands](https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src-tauri/src/commands/mod.rs): Native bridge · Rust command surface for filesystem, images, Steam/local Steam, official-site lookup, and folder opening. · `src-tauri/src/commands/mod.rs`
- [File commands](https://github.com/thelordofdino4/steam-backup-label-studio/blob/main/src-tauri/src/commands/files.rs): Rust fs · Native file access and folder-open behavior used by the desktop shell. · `src-tauri/src/commands/files.rs`

## Connections

- App entry → App shell: boots · Application entry mounts the top-level shell.
- App shell → Home screen: shows · App shell can present the home screen.
- App shell → Sidebar panels: composes · App shell assembles the sidebar control panels.
- App shell → Preview shell: composes · App shell assembles the live preview workspace.
- App shell → Case shell: switches to · App shell can route into the case-insert workspace.
- App shell → Project state: loads state · App shell reads and updates the canonical project model.
- Project state → Restore/snapshot: restores · Saved project files are normalized and restored through the lifecycle layer.
- Project state → Feature adapters: adapts · Feature-specific project slices are owned through adapters.
- Project state → Artwork assets: references assets · Project state stores artwork and built-in asset provenance.
- Disc editor → Project state: updates · Disc editor hooks synchronize UI actions into project state.
- Disc editor → Disc text: controls · Disc editor state drives text editing and layout behavior.
- Disc editor → Disc templates: selects · Disc editor state selects and edits templates.
- Disc text → Layout engine: uses · Text layout depends on shared geometry and occupied-region rules.
- Disc templates → Layout engine: uses · Template behavior is grounded in shared layout geometry.
- Preview shell → Render models: renders via · Preview layers consume render models for live display parity.
- Render models → Export pipeline: feeds · Render models are drawn into export output.
- Export pipeline → Layout engine: uses · Export drawing uses the same layout and safe-zone rules as preview.
- Export pipeline → Project state: reads · Export pipeline reads normalized project data and feature state.
- Case shell → Case domain: drives · Case-insert shell is organized around the case-insert domain model.
- Case shell → Case preview: drives · Case-insert shell composes the case preview surface.
- Case domain → Layout engine: uses · Case-insert rules reuse shared layout contracts and safe zones.
- Artwork assets → Steam import: imports from · Artwork pipeline can source metadata and media from Steam.
- Artwork assets → Local sources: imports from · Artwork pipeline can source local files and screenshots.
- Artwork assets → Project state: stores into · Imported assets are normalized into project-owned state.
- Preview shell → Artwork assets: shows · Preview layers display imported and built-in artwork assets.
- Tauri commands → File commands: exposes · Native command module includes filesystem and folder-opening behavior.
- Steam import → Tauri commands: calls · Steam-related workflows bridge through Tauri commands when native access is needed.
- Local sources → Tauri commands: calls · Local file and screenshot discovery uses the native bridge.
- Sidebar panels → Project state: edits · Sidebar panels mutate project state through hooks and controls.
- Preview shell → Disc editor: interaction · Preview includes inline editing and drag interactions for the disc surface.