# Mobile Deployment Roadmap

**Date:** 2026-05-13
**Scope:** `apps/mobile` end-to-end ship to iOS App Store + Google Play
**Status:** Decomposition — each phase ships independently with its own spec.

---

## Where we are today

- `apps/mobile` is an Expo + React Native scaffold from the very first commit (`f7cfd2a initial`). It has the right deps (`expo-router`, `react-native-libsodium`, `expo-secure-store`, `expo-sqlite`, `expo-notifications`) but no real screens — just two placeholders ("ChatApp" landing, "Chats — placeholder").
- Earlier mobile work (image attachments, voice messages, voice calls, reactions, profile editing, push wiring) lives on the archived `byGalax/chat-app` GitHub repo. It targets a pre-Tauri→Electron `packages/shared` API and is not directly portable; we treat it as reference material, not a merge source.
- `packages/shared` is platform-agnostic by design (`CryptoBackend` and `SecretStore` interfaces wait for mobile adapters), so the desktop's business logic is reusable verbatim once we plug in RN-flavoured implementations.
- The desktop reached `v0.17.5` with a Netralax rebrand, Discord-style call/chat UX, and an EAS-free electron-builder/electron-updater release pipeline pointed at `update.netralax.cloud`.

## Goal

Ship the Netralax mobile app to iOS App Store + Google Play with the core Discord-style chat + voice/video calls of the desktop, working over the same self-hosted Supabase + LiveKit backend.

## Decomposition

Five phases, each with its own design spec, plan, and ship gate. We brainstorm and execute one at a time; later phases only get fleshed out once their prerequisites land.

### Phase 0 — Deployment Foundation
**Spec:** `2026-05-13-mobile-phase-0-foundation-design.md`
**Goal:** prove the pipeline. After Phase 0, `eas build` (or `expo run`) produces a runnable Netralax-branded shell on a real iPhone + Android device. No features yet — but every later phase ships through this same build pipeline.

### Phase 1 — Auth + Chat MVP
**Why next:** smallest end-to-end vertical slice that's actually useful. Users can log in, see conversations, send/receive text.
- Mobile `CryptoBackend` adapter wrapping `react-native-libsodium`.
- Mobile `SecretStore` adapter wrapping `expo-secure-store`.
- Magic-link auth + device-key registration (reuse `packages/shared/auth`).
- Conversation list (DM + group) with last-message preview.
- Conversation view: decrypt + render text messages, send text.
- Push notifications via `expo-notifications` + the existing `notify-push` edge function.
- Minimal profile + logout.

### Phase 2 — Messaging Features
**Why next:** mobile users expect parity with desktop on day-to-day messaging.
- Image attachments (camera roll + camera capture).
- File attachments (document picker).
- Voice messages (record + play).
- Reactions, edit, delete, reply, forward.
- Read receipts + delivery state.
- Typing indicator.
- Polls (optional / stretch).

### Phase 3 — Voice/Video Calls
**Why now and not Phase 1:** RN LiveKit + native call UX (CallKit / ConnectionService) is the heaviest single feature. Hard to scope without the basic chat working first, and not blocking for an early TestFlight.
- LiveKit React Native SDK (`@livekit/react-native` + `@livekit/react-native-webrtc`).
- Incoming call notifications wake the app via CallKit (iOS) + ConnectionService (Android).
- Outgoing call flow.
- Voice + video tracks, mute/hangup, speaker/earpiece switch, headset routing.
- Screen sharing is explicitly out of scope on mobile.

### Phase 4 — Polish + Store Submission
**Why last:** can't submit until the features are in.
- Privacy policy + Terms surfaced inside the app.
- Store-listing assets: screenshots, descriptions, age rating.
- Code signing: Apple Developer Program enrolment + provisioning, Android upload keystore.
- TestFlight internal + external testing.
- Google Play internal track → closed test → production.

## Cross-cutting decisions (locked in here, no per-phase relitigation)

| Topic | Decision | Rationale |
|---|---|---|
| Framework | Expo + React Native (existing scaffold) | Already set up; New Architecture enabled; managed-workflow gives EAS Build out of the box |
| Branding | Netralax everywhere | Matches the desktop rebrand released as v0.17.x |
| Bundle / package id | `cloud.netralax.app` (both iOS + Android) | Matches the desktop's AppUserModelId `cloud.netralax.desktop`; `com.meinname.chatapp` is dev-placeholder |
| Shared business logic | Consume `@chat-app/shared` verbatim | Designed for this; the only mobile-specific pieces are the `CryptoBackend` + `SecretStore` adapters |
| Old chat-app mobile sprints | Reference, do not merge | API drift since pre-Electron; cleaner to rewrite against current shared |
| Backend | Self-hosted Supabase at `update.netralax.cloud` + LiveKit | Unchanged from desktop |
| Push delivery | Expo Push Service for development; native APNS + FCM after EAS submit | Avoids managing certs in Phase 1 |
| State management | React local state + tiny context, same as desktop | Avoid Redux/Zustand bloat for a chat app |
| Persistent local store | `expo-sqlite` (already in deps) | Mirror desktop's better-sqlite3 schema |

## Ship gates between phases

A phase only ends — and the next one begins — when:
1. Manual verification of every spec'd flow passes on **both** an iOS device and an Android device.
2. The previous phase's release build still runs (no regression).
3. The phase's spec is reflected in the codebase (no straggling TODOs that were in scope).

## Out of scope for the entire roadmap

- Web build of the mobile app (Expo can technically emit one — not worth the bundle-cost double-duty since the Electron app already covers desktop).
- macOS / Windows React Native targets.
- Watch / TV / wearable apps.
- iPad-specific UI tuning beyond `"supportsTablet": true` (we ship the phone UI on tablet for now).
- Resurrecting any code from the archived `chat-app` mobile sprints.