Day 03 — The Sanctum Boundary: React Shell, Rust Core, SQLite Codex

A door is only as trustworthy as the ward that guards it.

What we set out to build

• Problem: A launcher becomes a tangled temple fast if the UI, scanning, launching, and metadata all blur together. We needed a boundary that keeps the app fast, safe, and maintainable.
• Promise: Keep Gammoridin local-first and secure by default: the React UI is a presentation sanctum, while the Rust backend holds the real power—filesystem/registry scanning, launching, play tracking, SQLite writes, and IGDB enrichment.

Today’s focus was to lock in the shape of the system: a clear flow from UI → commands → modules → SQLite, with no “just let the frontend do it” shortcuts.

What shipped today

• ✅ Confirmed the core boundary: React/TypeScript renders and orchestrates, while Rust executes privileged work via Tauri commands (scanning, launching, tracking, DB, IGDB).
• ✅ Codified the data flow: Scan → normalize → upsert → list → render is the steady rhythm for library state, and Launch → track → persist → refresh UI is the rhythm for play sessions.
• ✅ Reinforced the local-first Codex: SQLite is the single source of truth for games, play sessions, settings, and cached IGDB metadata/art paths—no shadow state, no hidden “UI-only truth.”

Behind the curtain

The choice

We’re deliberately building Gammoridin as two honest halves:

• React (the Sanctum):
  It displays the library grid, filters, the Chronicle panel, and the Backlog Board. It asks for work through invoke() and then renders the results. That’s it. No credential handling. No direct IGDB calls. No filesystem spelunking.

• Rust (the Forge + Wards):
  The backend owns the “sharp tools”:

  • scanning across Steam/Epic/standalone heuristics
  • launching strategies (steam://rungameid/<id> vs direct exe + args)
  • session tracking (start → wait for exit → duration)
  • SQLite queries and upserts
  • IGDB enrichment + local caching

This division is not just style—it’s security and stability. The biggest proof point is IGDB: credentials remain backend-only, injected at build time, never stored in DB/settings, never exposed to the UI. That keeps the Codex powerful without cracking the Sanctum open.

We also leaned into a practical performance rule: anything heavy (scan batches, first-run forging, background IGDB sync) needs to be UI-thread safe. In practice that means being disciplined about async boundaries and using blocking work off the UI thread when appropriate.

The cut

We didn’t expand scope today—even though the architecture is “future-ready.”

Cuts we’re keeping intentional:

• No cloud sync in the core loop yet (statuses, favorites, play history stay local).
• No deals/affiliate tab wiring yet (even though the architecture anticipates it).
• No achievement scraping, no platform API reliance, and no private endpoints.
• No “telemetry creep.” The Chronicle is local, the Codex is local, and the player’s machine is the truth.

The architecture is allowed to anticipate the future. It is not allowed to pretend the future shipped.

Rough edges / dragons

• ⚠️ Scan quality still matters more than scan quantity. False positives erode trust fast; we need stricter junk-folder rejection and safer heuristics before we celebrate “more coverage.”
• ⚠️ Filtering can get expensive as libraries grow. The pipeline is clear and logical, but memoization/batching may be needed to keep the Sanctum snappy under load.
• ⚠️ Logging needs a real shape. We have known cleanup to do around structured logging (and we must keep secrets sealed—no tokens, no creds, no auth headers).
• ⚠️ Schema drift is a recurring risk. The DB, the docs, and the command surface have to stay in lockstep or everything becomes a haunted temple of mismatched assumptions.

Next on the path

• 🔜 Chronicle polish pass: better loading/error states, fallbacks for missing art, and consistent Codex styling across the detail panel.
• 🔜 Scanner cleanup: reduce junk entries, harden install heuristics, and keep everything legal/TOS-safe.
• 🔜 IGDB validation sweep: test across a real variety of games to ensure metadata + covers store correctly without credential leakage.
• 🔜 Documentation sync cadence: keep ARCH-NOTES, DB-SCHEMA, and CHANGELOG reflecting the living system—not an older ghost of it.
• 🔜 Backlog Board polish: verify sort_index persistence and drag/drop rules remain spec-aligned and satisfying.

— Filed into the Chronicle.