Sprimo/docs/ARCHITECTURE.md

Sprimo Frontend Architecture

Workspace Layout

• crates/sprimo-app: process entrypoint and runtime wiring.
• crates/sprimo-tauri: Tauri 2.0 alternative frontend entrypoint.
• crates/sprimo-api: axum-based localhost control server.
• crates/sprimo-config: config schema, path resolution, persistence.
• crates/sprimo-platform: platform abstraction for overlay operations.
• crates/sprimo-protocol: shared API/state/command protocol types.
• crates/sprimo-runtime-core: shared runtime core for command/state/API orchestration.
• crates/sprimo-sprite: sprite pack manifest loading and fallback logic.

Runtime Data Flow

1. Frontend (sprimo-app or sprimo-tauri) initializes sprimo-runtime-core.
2. Runtime core loads/creates config.toml and builds initial FrontendStateSnapshot.
3. Runtime core starts sprimo-api on a Tokio runtime.
4. API authenticates commands and deduplicates IDs.
5. Commands are bridged from API channel into frontend-specific command handlers.
6. Frontend adapter applies rendering/window effects and runtime core applies snapshot/config state.
7. Shared snapshot is exposed by API via /v1/state and /v1/health.

Sprite Reload Semantics

• SetSpritePack uses a two-phase flow:

1. Validate and build candidate pack runtime (manifest + clips + atlas layout + texture handle).
2. Commit atomically only on success.

• On reload failure, current pack remains active and snapshot last_error is updated.

Threading Model

• Main task: startup + shutdown signal.
• API task: axum server.
• Bridge task: forwards API commands into Bevy ingest channel.
• Bevy main thread: rendering, animation, command application, and window behavior.
• Tauri thread/runtime: webview UI, event loop, and runtime command consumer.
• Optional hotkey thread (Windows): registers global hotkey and pushes recovery events.
• Snapshot is shared via Arc<RwLock<_>>.

Design Constraints

• Bind API to localhost only.
• Token auth by default for mutating and state endpoints.
• Keep protocol crate renderer-agnostic for future backend/frontend reuse.
• Keep platform crate isolated for per-OS implementations.