first

docs/architecture.md

@@ -0,0 +1,50 @@
+# Architecture
+
+## System Shape
+
+Hermes uses three layers:
+
+- Native client apps for iOS and Android
+- A Rust backend API that owns timing and state
+- PostgreSQL plus Valkey for durable and short-lived data
+
+## Client Responsibilities
+
+- Render the study experience
+- Play preview and reveal video
+- Handle gestures and haptics
+- Show odds and lock timing
+- Keep local session state
+- Prefetch media
+- Sync clocks with the server
+- Capture structured analytics
+- Load English and Swedish strings from localization assets
+
+## Backend Responsibilities
+
+- Auth and session binding
+- Event feed and manifests
+- Markets and odds distribution
+- Bet intent validation and acceptance
+- Settlement and audit logging
+- Experiment assignment
+- Localization bundle serving
+- Analytics ingestion
+- Admin fixture publishing
+
+## Core Rules
+
+- The server decides lock time and settlement
+- Clients send intent, not fairness decisions
+- Video playback must not block overlay updates
+- Client and server state machines must match
+- Localization is mandatory for every user-facing string
+- Analytics and audit data stay relational
+
+## Repo Order
+
+1. Documents and contracts
+2. Backend foundation
+3. Domain modules and API coverage
+4. Fixture and admin workflows
+5. Native iOS and Android apps