# 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](native-parity.md), 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.