How thelordofdino4/steam-backup-label-studio works
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: projectSchema.ts Project state · App.tsx App shell · assetManifest.ts Artwork assets · DiscPreview.tsx Preview shell
Components 23
App Shell
React entrypoints, top-level composition, and shared UI surfaces.
- App entry · Starts the desktop UI and mounts the app shell.
src/main.tsx - App shell · Routes the main workspace and coordinates home/editor surfaces.
src/app/App.tsx - Home screen · Landing surface and navigation into the editor workflow.
src/components/home/HomeScreen.tsx - Sidebar panels · Reusable sidebar panels for project, metadata, artwork, branding, text, templates, and export controls.
src/components/sidebar/ProjectPanel.tsx - Preview shell · 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 · Canonical project schema, normalization, restore/snapshot logic, routing, and feature adapters.
src/project/projectSchema.ts - Restore/snapshot · Creates snapshots and restores normalized project state from saved files.
src/project/createProjectSnapshot.ts - Feature 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 · Disc-specific physical geometry and safe-zone constraints.
src/disc/geometry.ts - Disc text · Curved and straight disc text layout, avoidance, styles, and inline editing support.
src/discText/index.ts - Disc templates · Disc template defaults and layout contracts for the current alpha surface.
src/templates/discTemplates.ts - Disc editor · 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 · Case-insert editor shell and workflow organization for jewel-case surfaces.
src/components/caseInsert/CaseInsertEditorShell.tsx - Case domain · Case-insert templates, text, branding, spine, banner, title artwork, and export settings.
src/caseInsert/types.ts - 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 · Local uploads, built-in assets, image utilities, and asset manifests.
src/assets/assetManifest.ts - Steam import · Steam metadata, logo candidates, artwork import, platform marks, and auto-apply logic.
src/steam/steamMetadataCandidates.ts - Local sources · 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 · Shared safe zones, occupied regions, guide layouts, and physical placement rules.
src/layout/discElementSafeZone.ts - Render models · Maps project state into render models for layers and export drawing.
src/render/artworkFrame.ts - Export pipeline · 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 · Rust command surface for filesystem, images, Steam/local Steam, official-site lookup, and folder opening.
src-tauri/src/commands/mod.rs - File commands · Native file access and folder-open behavior used by the desktop shell.
src-tauri/src/commands/files.rs
Connections 30
- 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.