Yuvomi-App/docs/architecture.md

Native client architecture

The requested product is a native reconstruction of Yuvomi's PWA, not a native window around that website. Both shipping entry points now render native views:

Responsibility	Android	iOS
Screens and navigation	Jetpack Compose / Material 3 primitives, Yuvomi tokens	SwiftUI, Yuvomi tokens
Application state	AndroidViewModel + Compose state	MainActor ObservableObject
JSON API	HttpsURLConnection, serialized worker	URLSession actor, bounded streaming delegate
Session ownership	Explicit origin-bound HTTPS-only cookie jar	Private ephemeral URLSession cookie storage
Persistent cookies	AES-GCM, AndroidKeyStore key, origin as authenticated data	Keychain, WhenUnlockedThisDeviceOnly, origin-scoped account
Server logic	Existing unmodified Yuvomi API	Existing unmodified Yuvomi API

There is no WebView/WKWebView in either shipped source tree and no browser fallback for missing modules. The old implementation and browser tests are archived in legacy/; their results are historical, not evidence for this client.

The first native slice contains HTTPS onboarding, setup/password/TOTP login, session restoration, a basic dashboard, task/note/shopping interactions, read-only permission handling and local sign-out/server removal. Exact feature and visual parity is tracked in native parity, not inferred from a list of navigation destinations. The other modules remain unfinished.

Transport and state boundaries

• One configured root HTTPS origin/port; system certificate validation only.
• API calls never follow redirects. No cookie or Authorization state is replayed to another host. Authentication proxies returning HTML are not treated as APIs.
• JSON reads have byte limits and timeouts. Writes are not queued for offline replay. Only a server-declared csrf_invalid rejection permits one token refresh and retry; ordinary authorization failures and transport failures do not.
• Server session cookies are persisted, not passwords or TOTP/recovery codes. Session-only cookies are not converted to long-lived cookies.
• Native UI mutations wait for the server result. Permissions remain enforced server-side; sparse module/widget permissions also control native affordances.
• Android's native jar enforces HTTPS itself rather than rejecting a valid server cookie solely because its Secure attribute is absent. This supports upstream's default session settings behind HTTPS proxies without permitting HTTP or cross-origin cookie replay. Browser cookie configuration remains the server operator's responsibility; SESSION_SECURE=true is recommended for HTTPS sites.
• Local removal clears the native cookie vault and in-memory records. It is not remote revocation. Logout attempts server revocation and still erases the local session if the server cannot be reached.
• A prior WebView prototype installation may retain its old OS website data. This data is never imported by the native client. Clear app data/reinstall the prototype before reviewing this native preview if complete legacy erasure is required; no migration of private household records is performed.

Explicit gaps

No native OIDC handoff has been implemented. A browser sign-in is not represented as a successful native API session. Password reset/invitation flows, the remaining modules, configurable dashboard, uploads/downloads, notification integrations, offline cache, localization parity and visual baseline comparison remain open. The signing setup was paused by the maintainer's native-rebuild correction; it must not be used to label this incomplete client as a finished release.