# 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.