hermes/docs/architecture.md

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