47 lines
2.1 KiB
Markdown
47 lines
2.1 KiB
Markdown
# 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.
|