Add: windows mvp - transparent bugs not fixed

docs/ARCHITECTURE.md

@@ -0,0 +1,43 @@
+# Sprimo Frontend Architecture
+
+## Workspace Layout
+
+- `crates/sprimo-app`: process entrypoint and runtime wiring.
+- `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-sprite`: sprite pack manifest loading and fallback logic.
+
+## Runtime Data Flow
+
+1. `sprimo-app` loads or creates `config.toml`.
+2. App builds initial `FrontendStateSnapshot`.
+3. App starts `sprimo-api` on a Tokio runtime.
+4. API authenticates commands and deduplicates IDs.
+5. Commands are bridged from Tokio channel to Bevy main-thread systems.
+6. Bevy systems apply commands to sprite state, window/platform operations, and config persistence.
+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.
+- 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.