# Kaizen App — Future Implementation & Architecture Roadmap (LATER)

This document serves as a persistent repository of high-level architectural blueprints, native security concepts, and backend orchestration models for the **Kaizen Native Android App**. 

To maintain clean execution and avoid technical debt, backend-dependent features and device-level hardware cryptography are documented here for implementation in later phases.

---

## 🛡️ 1. Native Hardware Cryptography & Security

When transitioning from the Web PWA to the native Android App, we can leverage Android OS-level hardware security that is completely unavailable to standard webbrowsers.

### A. Android KeyStore System (API 23+) — ✅ DONE (Phase 1)
> Implemented in `net/SecureStore.kt`: the `kzn_` bearer token is stored in
> `EncryptedSharedPreferences` (AES-256-GCM, KeyStore-backed). Only this item
> graduated — biometrics binding (§C) and `FLAG_SECURE` (§B) stay deferred.

* **Concept:** Instead of storing API keys or session tokens in plain-text `SharedPreferences` (which are readable on rooted devices), we will use Android's `EncryptedSharedPreferences`.
* **Mechanism:** 
  - Uses the **hardware-backed KeyStore** (StrongBox / Secure Enclave on flagship devices like the S25 Ultra or Google Pixel 10).
  - Automatically encrypts keys and values using AES-256-GCM.
  - Encryption keys are kept inside the hardware chip and cannot be leaked even if the OS is compromised or rooted.
* **Orchestration with Backend:**
  - Since the Web app encrypts API keys using AES-256 in PostgreSQL, the Android app can either query the decrypted key securely via HTTPS from the backend during a chat leg (if the server acts as the API proxy), OR store a copy of the key locally encrypted in the Android KeyStore for offline direct client-side requests.

### B. Prevention of Screen Scraping (`FLAG_SECURE`)
* **Concept:** Prevent malware, unauthorized users, or background tasks from taking screenshots or recording the screen on sensitive areas of the app (e.g., chat logs, settings, API-key inputs).
* **Implementation:** 
  - Set the secure flag dynamically on the Window inside activities or specific composables:
    ```kotlin
    activity?.window?.addFlags(WindowManager.LayoutParams.FLAG_SECURE)
    ```
  - System-wide screenshots are instantly blocked (generates a black image), and the app's preview in the system app-switcher/task-manager is automatically blanked/censored.

### C. Keystore-Biometrics Binding
* **Concept:** Tie the decryption of chat databases or API keys directly to a successful biometrics authorization.
* **Mechanism:** 
  - Generate an AES key in the KeyStore that is **specifically configured to require biometrics** (`setUserAuthenticationRequired(true)`).
  - The Android CPU's Secure Enclave will literally refuse to release the decryption key to memory unless the native `BiometricPrompt` returns a hardware-validated success signal.

---

## 🔑 2. Biometric Lockscreen & Auth-Sync

The biometric lockscreen is delayed until the backend sync logic is built, as it requires a secure session verification handshake.

### A. Instant Biometric Prompt
* **API:** `androidx.biometric.BiometricPrompt`
* **Flow:** On app launch or when selecting a locked chat from the sidebar:
  1. Trigger the native system Biometric prompt (supporting Fingerprint on S25 Ultra, Face Unlock, or PIN fallback).
  2. On success, use the returned cryptographic `Cipher` to decrypt the local DB or session token.
  3. Seamlessly slide into the main interface.

### B. Translucent Glass PIN-Pad Fallback
* **Design:** For devices without biometrics or on fallback, render a custom, highly blurred frosted-glass PIN-pad.
* **Haptics:** Synchronize each button press with a native, precise tactile click vibration.
* **Visuals:** The `KaizenOrb` floats dynamically above the PIN-pad, glowing red on locked state, breathing in amber on typing, and flashing in bright emerald/amber on successful unlock.

---

## 🌐 3. Backend Synchronization & Streaming Orchestration

### A. Next.js Session/Cookie Proxy
* **Challenge:** The web app uses Auth.js (NextAuth) with secure `httpOnly` cookies.
* **Solution:** 
  - The Android app's HTTP client (e.g., Ktor or Retrofit) will maintain a persistent `CookieJar`.
  - When logging in via credentials or native Passkeys, the backend sets the Auth.js session cookie, which is automatically attached to subsequent API calls.

### B. High-Speed WebSocket Streaming
* **Concept:** Instead of polling or standard server-sent events (SSE) which can be unstable on mobile networks, establish a dedicated WebSocket channel for the chat stream.
* **Advantages:** Extremely low latency, full-duplex communication (allows instant interrupt/Stop signals from the client), and perfect synchronization with the breathing frequency of the `KaizenOrb`.

---

## 📈 4. Progressive High-End Visuals

### A. Ultra HDR with Gainmaps (Android 14+ / API 34)
* **Concept:** Boost highlights (like the shiny glint of the `KaizenOrb` or glowing buttons) to actual HDR peak brightness (up to 1000+ nits) on high-end AMOLED screens.
* **Implementation:** Enable `ActivityInfo.COLOR_MODE_HDR` on the window and write custom AGSL shaders for the glowing canvases.

### B. Gyroscope-Responsive 3D Parallax
* **Optimization:** Keep the gyroscope tilt listener running on UI thread delays (`SENSOR_DELAY_UI`) and clamp tilt limits tightly. Ensure a complete unregister listener call on app pause to conserve 100% battery efficiency.