ChatApp/docs/superpowers/specs/2026-05-13-mobile-phase-0-foundation-design.md

Mobile Phase 0 — Deployment Foundation

Date: 2026-05-13 Scope: apps/mobile Roadmap context: 2026-05-13-mobile-deployment-roadmap.md

---

Problem

We can't even smoke-test a Netralax-branded build on a real device today. The Expo scaffold says "ChatApp" everywhere, the EAS project ID is a literal string REPLACE_WITH_EAS_PROJECT_ID, and the iOS bundle id / Android package id is the placeholder com.meinname.chatapp. Every later phase ships through this build pipeline, so it needs to work end-to-end before we touch features.

Goal

After Phase 0, a developer (or the user) can run a single command from the repo root and get an installable .ipa or .apk carrying the Netralax brand. No real features — just a launch screen that renders, plus the harness underneath: SafeArea, navigation root, error boundary, the @chat-app/shared package compiling and importable from the mobile app, version readout, EAS config.

Non-goals

• Auth, chat, calls, push wiring (Phases 1–3).
• App Store / Play Store submission (Phase 4).
• Resurrecting the legacy mobile sprints from the archived chat-app repo.
• Code-signing certificates / provisioning profiles. Phase 0 produces development-signed builds via EAS managed credentials; production signing is Phase 4.

Design

1. Branding rename in apps/mobile/app.json

Replace every ChatApp/com.meinname.chatapp reference with the Netralax brand. Final values:

{
  "expo": {
    "name": "Netralax",
    "slug": "netralax",
    "scheme": "netralax",
    "version": "0.1.0",
    "ios": {
      "bundleIdentifier": "cloud.netralax.app",
      "supportsTablet": true,
      "infoPlist": { "ITSAppUsesNonExemptEncryption": false }
    },
    "android": {
      "package": "cloud.netralax.app",
      "adaptiveIcon": {
        "foregroundImage": "./assets/adaptive-icon.png",
        "backgroundColor": "#0b0b0f"
      }
    },
    "extra": { "eas": { "projectId": "REPLACE_WITH_EAS_PROJECT_ID" } }
  }
}

extra.eas.projectId stays as the placeholder string in source — the user runs eas init once locally, which fills it in and commits. Documented in the mobile README.

2. App icon + splash

Replace assets/icon.png, assets/adaptive-icon.png, assets/splash.png with placeholder Netralax variants (purple-on-dark N mark matching the sidebar avatar in the desktop). A single 1024×1024 master plus the 1024-Android-foreground and 1284×2778 splash is enough for Phase 0. Final art lives in apps/mobile/assets/.

3. EAS configuration

Create apps/mobile/eas.json:

{
  "cli": { "version": ">= 13.0.0" },
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal",
      "ios": { "simulator": true },
      "android": { "buildType": "apk" }
    },
    "preview": {
      "distribution": "internal",
      "ios": { "simulator": false },
      "android": { "buildType": "apk" }
    },
    "production": {
      "ios": { "simulator": false },
      "android": { "buildType": "app-bundle" }
    }
  },
  "submit": {
    "production": {
      "ios": { "appleId": "REPLACE_WITH_APPLE_ID", "ascAppId": "REPLACE_WITH_ASC_APP_ID" },
      "android": { "serviceAccountKeyPath": "./play-service-account.json" }
    }
  }
}

production-submit credentials stay as placeholders — Phase 4 fills them in. The development profile produces a custom dev client + APK that can be installed and used with expo start --dev-client.

4. Minimal app shell that doesn't crash

Four changes to verify the runtime is healthy:

• app/_layout.tsx: wrap the <Stack> in <SafeAreaProvider> from react-native-safe-area-context. Add <GestureHandlerRootView style={{ flex: 1 }}> outside it so future gesture-based UI is unblocked. Wrap everything in a top-level <ErrorBoundary> (new component, §4a) so an unhandled render error shows a readable fallback instead of a white-screen crash on a TestFlight build.
• app/index.tsx: render "Netralax" (not "ChatApp"), display the app version read from expo-application (Application.nativeApplicationVersion), and link to /(app)/chats via a placeholder button so navigation is proved.
• app/(app)/chats.tsx: same — render "Netralax — Chats coming soon" so the protected-stack mounts cleanly.

4a. Error boundary

apps/mobile/components/ErrorBoundary.tsx is a small React class component that catches render errors and shows the error message + a "Reload" button. Same shape as the desktop's crash-recovery surface. Around 40 lines.

5. Shared package smoke import

Phase 0's gate is that import { CryptoBackend } from '@chat-app/shared' resolves and the Metro bundler doesn't choke on the shared package's exports. We don't use the import — just type it so a compile failure surfaces here, not later.

Concretely: add apps/mobile/lib/sharedSmoke.ts that pulls a runtime value (not a type-only import — type imports are erased by the TS compiler and never reach Metro). @chat-app/shared re-exports its modules as namespaces (crypto, auth, chat, friends, rtc, supabase, i18n, admin), so we go through one of those:

// Force-imports a runtime symbol from @chat-app/shared so Metro
// actually resolves the package on app boot. A type-only import would
// be erased and never surface a packaging problem. This file goes away
// once Phase 1's real crypto adapter lands and registers the backend
// for real.
import { crypto } from '@chat-app/shared';

// Pull the function into a runtime reference so the bundle keeps the
// import. Calling it without a backend would throw, so we just retain
// the reference.
export const sharedSmoke = { register: crypto.setCryptoBackend };

Imported from _layout.tsx once, value unused. Phase 1 removes it.

6. README + scripts

apps/mobile/README.md gets a "Phase 0 quickstart" section that walks through eas init + the first development build + installing the dev client on a device.

Root package.json gets convenience scripts only if they're missing: mobile:dev, mobile:ios, mobile:android, mobile:typecheck — all pnpm --filter @chat-app/mobile <cmd> wrappers.

7. Typecheck + lint plumbing

Verify pnpm --filter @chat-app/mobile typecheck already runs (the mobile package.json already declares it). If eslint is wired similarly, add it to a CI workflow stub — but actual CI integration is out of scope here.

File structure (after Phase 0)

apps/mobile/
├── app/
│   ├── _layout.tsx           ← MODIFIED: SafeArea, GestureHandler, providers shell
│   ├── index.tsx             ← MODIFIED: Netralax landing with version + nav link
│   └── (app)/
│       ├── _layout.tsx       ← unchanged
│       └── chats.tsx         ← MODIFIED: "coming soon" placeholder text
├── assets/
│   ├── icon.png              ← REPLACED: Netralax 1024×1024
│   ├── adaptive-icon.png     ← REPLACED: foreground for Android adaptive
│   └── splash.png            ← REPLACED: Netralax splash
├── lib/
│   └── sharedSmoke.ts        ← NEW: temporary import-canary
├── app.json                  ← MODIFIED: Netralax branding, ids
├── eas.json                  ← NEW: build profiles
├── package.json              ← unchanged (deps stay)
└── README.md                 ← MODIFIED: Phase 0 quickstart

Risks

• react-native-libsodium + New Architecture (Fabric / TurboModules). newArchEnabled: true is in app.json. The library claims support, but past RN libsodium ports broke around the JSI migration. If the dev client crashes on require, fall back to disabling new arch in Phase 0 and re-enable in Phase 1 once the adapter is wired and tested.
• @chat-app/shared Node-only paths. The package was authored against Node + browser; the supabase client uses fetch and WebSocket which RN polyfills. If any export pulls node:crypto directly the Metro resolver may fail. The smoke import (§5) is the canary for this.
• EAS account access. eas init requires an Expo account. The user owns it; we treat the project ID slot as an external input.
• Apple Developer enrolment. Phase 0 builds for iOS need an Apple ID; EAS can generate dev certs automatically the first time eas build --platform ios runs against the user's Apple ID. No paid enrolment needed for the development profile (free signing).

Verification (run before declaring Phase 0 done)

1. pnpm --filter @chat-app/mobile typecheck → exit 0.
2. pnpm --filter @chat-app/mobile dev (expo start --dev-client once a dev client is installed) → app boots on a real iPhone and a real Android device.
3. Landing screen shows "Netralax" + a non-empty version string read at runtime.
4. Tapping the placeholder nav link routes into /(app)/chats without crash.
5. eas build --platform android --profile development produces an APK that installs and launches on a physical Android device.
6. eas build --platform ios --profile development produces a .tar.gz (simulator build) OR an .ipa (device build, if free signing succeeded).
7. Optional: visual check that the icon + splash render as Netralax (not Expo's default) on both platforms.

If any of those fail, Phase 0 isn't done — fix in this phase rather than rolling it into Phase 1.

Out of scope

• Push notification token registration (Phase 1).
• Linking to the Supabase URL / env-var injection (Phase 1).
• Local SQLite schema (Phase 1).
• Any screen beyond Landing + Chats-coming-soon.
• Reanimated / gesture-based animations.
• Dark / light mode polish — system default is fine.