kaizen-app/LATER.md

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:

    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.