omarchy-sc/ARCHITECTURE.md

Citizen Launcher architecture

One source of truth

The Go core under backend/cmd/citizen-launcher owns detection, setup, repair, launch, maintenance, support and self-update. Shell/QML integrations are adapters only; they must not duplicate the gaming-stack implementation.

Standalone GUI / Omarchy adapter
              │
              ▼
       Citizen Launcher Go core
              │
   ┌──────────┼───────────┐
   ▼          ▼           ▼
Preflight   Wine       RSI metadata
            selector       │
            + test          ▼
   │          │       verified installer
   └────┬─────┘             │
        ▼                   ▼
        managed Wine prefix
        │       │        │
        ▼       ▼        ▼
   Winetricks  DXVK  PowerShell wrapper
        └───────┬────────┘
                ▼
          RSI Launcher / Game

Activation model

Mutable downloads are staged first. Executable GitHub release assets require a SHA-256 digest. A Wine candidate is extracted to a staging directory, tested against a throw-away prefix, and only then becomes vendor/wine/current. The previous validated runner is retained.

The real game prefix is never used as the Wine compatibility test target.

Concurrency model

• gui.lock: one GUI backend process per user.
• in-memory GUI job gate: one long-running GUI action at a time.
• maintenance.lock: cross-process serialization of setup/repair/maintenance/launch transition.
• /proc exact WINEPREFIX inspection: maintenance is deferred while user-facing prefix processes are active.
• launch path rechecks RSI/Star Citizen after acquiring the stack lock, closing the double-click race.

GUI

The UI is embedded in the static binary. It binds an ephemeral port on 127.0.0.1 and uses a cryptographically random per-process route token. No remote web content is needed. A second citizen-launcher gui discovers the locked instance and reopens that URL instead of spawning another backend.

Distribution boundary

Citizen Launcher manages Wine/DXVK/RSI in XDG user directories. It does not replace distribution GPU drivers, kernels or package update policy. Debian packaging supplies only the system limits and a narrowly scoped package self-update timer; interactive system preparation uses Polkit rather than passwordless sudo.