Add the native Hesychia Android client so the repo can build beyond the placeholder README.

docs/ADR-001-architecture.md

@@ -0,0 +1,34 @@
+# ADR-001: Architecture for native Hesychia Android
+
+- **Status:** Accepted (spike default)
+- **Date:** 2026-08-05
+- **Context:** Epic [chat_web_app#111](https://git.aimloperations.com/ai_ml_operations/chat_web_app/issues/111)
+
+## Decision
+
+Ship a **Kotlin + Jetpack Compose + Material 3** client in `chat_android`, single `:app` module for v1.
+
+| Concern | Choice |
+|---------|--------|
+| UI | Jetpack Compose + Material 3 (`HesychiaTheme` from design tokens) |
+| DI | Hilt |
+| REST | Retrofit + OkHttp + kotlinx.serialization |
+| WebSocket | OkHttp WebSocket (parity with FE `WebSocketContext`) — Workstream D |
+| Session | DataStore Preferences (JWT access/refresh); migrate to EncryptedSharedPreferences if threat model requires |
+| Nav | Navigation Compose |
+| IAP | RevenueCat Android SDK (`com.revenuecat.purchases`) |
+| Flavors | `prod` / `beta` (env dimension); debug adds `.debug` applicationIdSuffix |
+| Min / target SDK | 23 / 35 (match Capacitor shell) |
+| Application id | **`ai.hesychia.chat`** (same as Capacitor) — see ADR-002 |
+
+## Alternatives considered
+
+1. **Keep Capacitor only** — lower eng cost short-term; WebView UX / IAP friction remain.
+2. **Flutter** — one codebase for Android+iOS, but new stack vs existing Kotlin skill + no shared UI with React web.
+3. **Multi-module now** — premature until chat + auth + billing vertical slices exist.
+
+## Consequences
+
+- Feature modules (`:feature:auth`, `:feature:chat`, `:core:network`) deferred until MVP vertical slice ships.
+- iOS twin is a **separate epic / repo** (SwiftUI), not Flutter.
+- Visual parity bar: **brand + layout rhythm**, not pixel-perfect MUI clones.