Architecture on Replay Control

Technical Foundation

Wed, 01 Jan 2025 00:00:00 +0000

The core technical stack and infrastructure that powers Replay Control. For performance-specific design decisions, see Design Decisions.

Crates

The codebase is split into four crates inside a Cargo workspace.

Design Decisions

Wed, 01 Jan 2025 00:00:00 +0000

Replay Control is a single-user retro game management web UI that runs on Raspberry Pi. Every design decision is shaped by this target environment.

Startup Pipeline

Wed, 01 Jan 2025 00:00:00 +0000

BackgroundManager::start() in replay-control-app/src/api/background.rs orchestrates an ordered background pipeline and independent filesystem watchers.

Entry Point

BackgroundManager::start(state)
 -> tokio::spawn(run_pipeline) // sequential phases
 -> spawn_storage_watcher() // independent
 -> spawn_rom_watcher() // independent

If storage is unavailable at boot, only the storage watcher is spawned. When storage appears (None -> Some transition via refresh_storage()), the full pipeline starts.

Database Schema

Wed, 01 Jan 2025 00:00:00 +0000

Two SQLite databases live at <storage>/.replay-control/:

metadata.db – rebuildable cache (game library, external metadata, thumbnail index)
user_data.db – persistent user customizations (never auto-deleted)

Schema defined in replay-control-core-server/src/metadata/metadata_db/mod.rs and user_data_db.rs.

Server Functions and SSR

Wed, 01 Jan 2025 00:00:00 +0000

Defined across replay-control-app/src/main.rs, src/pages/, and src/server_fns/.

Leptos 0.7 SSR with WASM Hydration

The app uses server-side rendering with client-side WASM hydration. Four build profiles handle this:

Connection Pooling

Wed, 01 Jan 2025 00:00:00 +0000

Defined in replay-control-app/src/api/mod.rs.

Pool Architecture

Each SQLite database gets a DbPool instance backed by deadpool with a custom SqliteManager. The app has two pools:

Enrichment Pipeline

Wed, 01 Jan 2025 00:00:00 +0000

Pure data logic in replay-control-core-server/src/metadata/enrichment.rs. App orchestration in replay-control-app/src/api/cache/enrichment.rs and images.rs.

Architecture: Core / App Split

Core (`replay_control_core::enrichment`)

Pure data pipeline — no web server state, connection pools, or caches:

ROM Classification

Wed, 01 Jan 2025 00:00:00 +0000

Defined in replay-control-core/src/game/rom_tags.rs.

RomTier Enum

ROMs are classified into tiers that determine sort order (lower = shown first) and filtering behavior:

Activity System

Wed, 01 Jan 2025 00:00:00 +0000

Defined in replay-control-app/src/api/activity.rs. Provides mutual exclusion for long-running operations and real-time progress broadcasting to the UI.

Design

At most one activity runs at a time. The state is stored in AppState::activity (Arc<RwLock<Activity>>) and broadcast to SSE clients via AppState::activity_tx (a tokio::sync::broadcast channel).

Architecture on Replay Control

Technical Foundation

Crates

Design Decisions

Startup Pipeline

Entry Point

Database Schema

Server Functions and SSR

Leptos 0.7 SSR with WASM Hydration

Connection Pooling

Pool Architecture

Enrichment Pipeline

Architecture: Core / App Split

Core (replay_control_core::enrichment)

ROM Classification

RomTier Enum

Activity System

Design

Core (`replay_control_core::enrichment`)