chat_android/docs/ADR-001-architecture.md

ADR-001: Architecture for native Hesychia Android

• Status: Accepted (spike default)
• Date: 2026-08-05
• Context: Epic chat_web_app#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.