# 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