Toju/agents-docs/features/mobile-capacitor.md

Mobile Capacitor

Cross-context mobile shell for the Angular product client (toju-app/). Wraps the existing SPA in Ionic Capacitor native projects (toju-app/android/, toju-app/ios/) while keeping Capacitor APIs behind toju-app/src/app/infrastructure/mobile/.

Responsibilities

• Detect runtime shell (browser, capacitor, electron) without importing native plugins in domain code. Capacitor packages and adapters load only on capacitor shells via dynamic import() so Electron/desktop startup never evaluates @capacitor/* modules.
• Expose facades for notifications, in-call controls, media/attachments, stream pop-out, background audio session, CallKit, and native persistence.
• Integrate with direct-call, voice-workspace, and chat composer flows.

Boundaries

Layer	Owns
infrastructure/mobile/	Platform detection, plugin lazy-loading, web/Capacitor adapters
infrastructure/persistence/	DatabaseService routing (browser / capacitor-sqlite / electron)
Domains (direct-call, chat, voice-session)	Business orchestration; inject mobile facades only
core/platform/PlatformService	Adds isCapacitor flag for persistence routing
Capacitor native projects	OS permissions, push certificates, store packaging

Build & run

# Production web bundle (Capacitor webDir)
npm run build:prod

# Copy web assets into native projects
npm run cap:sync

# Open IDE
npm run cap:open:android
npm run cap:open:ios

### Linux: Android Studio path

Capacitor defaults to `/usr/local/android-studio/bin/studio.sh`. If Android Studio is installed elsewhere (common with **Flatpak** from Flathub), `npm run cap:open:android` uses `tools/resolve-android-studio-path.js` to locate `studio.sh` (Flatpak `active` symlink, Toolbox, snap, `/opt`, etc.). Override anytime with `CAPACITOR_ANDROID_STUDIO_PATH`.

# Convenience (build + sync + open)
npm run cap:build:android
npm run cap:build:ios

# CI / Linux: production web bundle + Capacitor sync + Gradle debug APK
npm run cap:apk:android
# → toju-app/android/app/build/outputs/apk/debug/app-debug.apk

Config: toju-app/capacitor.config.ts (webDir: ../dist/client/browser).

CI (Gitea)

Release workflow .gitea/workflows/release-draft.yml builds a debug Android APK on every push to main / master (job build-android), stages it as Toju-<version>-android-debug.apk, and uploads it to the same draft Gitea release as the desktop .exe / .deb assets via tools/gitea-release.js.

Manual-only workflow .gitea/workflows/build-android-apk.yml (workflow_dispatch) repeats the same build and release upload on demand from any branch.

Both jobs install JDK 21 and Android SDK platform 36 inside the node:22 container and run tools/build-android-apk.sh. No signing keystore is configured — output is a debug APK suitable for sideloading and QA.

Optional google-services.json is not injected in CI; push registration in artifact builds follows the same optional-Firebase behavior as local unsigned debug builds.

After dependency or plugin changes, run npm run build:prod && npm run cap:sync so native projects register @capacitor/app, @capacitor-community/sqlite, @capawesome/capacitor-app-update, push plugins, and MetoyouMobile.

App icon & splash (Android brand assets)

The Capacitor shell must ship the Toju brand mark, not the stock Ionic/Capacitor placeholder. Brand resources are generated from images/icon-new-rounded.png (circular cat-on-purple disc) into toju-app/android/app/src/main/res/:

npm run cap:assets:android   # → tools/generate-android-app-icons.mjs (uses sharp)

This produces, for every density (mdpi … xxxhdpi):

• mipmap-*/ic_launcher.png + ic_launcher_round.png — legacy launcher bitmaps (the brand disc).
• mipmap-*/ic_launcher_foreground.png — full-bleed adaptive foreground; the adaptive layers in mipmap-anydpi-v26/ic_launcher*.xml reference @mipmap/ic_launcher_foreground (the stock drawable-v24/ic_launcher_foreground.xml vector is removed).
• values/ic_launcher_background.xml — adaptive background colour set to the brand purple #4A217A, not stock white.
• drawable*/splash.png (port + land per density, plus the base) — brand mark centred on a purple field for the launch splash.

Invariants are encoded in toju-app/src/app/infrastructure/mobile/logic/mobile-android-launcher-icon.rules.ts (required file set, brand background colour, and the SHA-256 of every stock Capacitor placeholder that must never reappear). Coverage:

• Unit: mobile-android-launcher-icon.rules.spec.ts — asserts every density is present, no resource matches a stock placeholder hash, and the adaptive background is the brand purple.
• E2E: e2e/tests/mobile/android-app-icon.spec.ts — same contract plus pixel checks (launcher ring is purple, centre is the white cat; splash corner is purple, centre is the cat). Deterministic; no emulator.

Re-run npm run cap:assets:android whenever images/icon-new-rounded.png changes; npm run cap:sync is not needed (resources live in the native project, not webDir).

Feature status

Feature	Status	Notes
Push/local notifications	Working (partial)	Local notifications always available; remote push (FCM/APNs) registers only when Firebase/APNs is configured — app starts normally without google-services.json
Server push dispatch	Working (configured)	Tokens persist in server SQLite; outbound FCM/APNs via env credentials
In-call notifications	Working (Capacitor)	Persistent notification with answer/mute/hang-up actions
Stream pop-out (PiP)	Working (partial)	Document PiP when WebView supports it; Android native PiP fallback via MetoyouMobile plugin
Background voice	Working (partial)	Android foreground service; iOS UIBackgroundModes audio + CallKit active-call bridge
iOS CallKit	Working (partial)	MetoyouMobile.startCallKitSession reports active calls; requires Xcode target wiring after cap:sync
Screensharing	Limited	Disabled on iOS WebView; Android getDisplayMedia may work
Composer attachments	Working	Mobile attachment button + hidden file input
Camera sharing	Working	Existing getUserMedia camera path in WebRTC stack
Speakerphone	Working (partial)	Android AudioManager via MetoyouMobile; iOS @capgo/capacitor-audio-session; direct-call speaker toggle on native mobile
Local DB (SQLite)	Working	DatabaseService routes Capacitor shells to CapacitorDatabaseService (native SQLite CRUD)
Store app updates	Working (partial)	@capawesome/capacitor-app-update via MobileAppUpdateService; Android in-app updates when Play allows, iOS opens App Store

Platform limitations

• iOS background WebRTC: OS may still suspend peer connections when backgrounded despite audio background mode and CallKit reporting.
• iOS CallKit: Plugin Swift source ships in ios/App/App/MetoyouMobilePlugin.swift; add it to the Xcode target if not auto-linked. Incoming-call UI is not fully bridged to WebRTC answer/hang-up yet.
• iOS screenshare: getDisplayMedia is not available in WKWebView.
• Android PiP: Native PiP enters activity-level PiP; WebView video may not always render inside PiP on all OEM WebViews.
• Production discovery: signal.toju.app may not expose /api/servers/featured or /trending; client skips those calls for known hosts.
• Push delivery: Requires FCM service account and APNs key configuration on the signaling server.

Push notification setup (FCM / APNs)

Android (FCM)

The app starts without Firebase. MobilePushRegistrationService probes MetoyouMobile.isRemotePushConfigured() (Firebase FirebaseApp on Android) before calling PushNotifications.register(); when unconfigured it logs a single warning and skips registration.

1. Create a Firebase project and add an Android app with package com.metoyou.app.
2. Copy toju-app/android/app/google-services.json.example to google-services.json (gitignored) and fill in your Firebase values.
3. Run npm run cap:sync so the Google Services Gradle plugin applies when the file is present (build.gradle applies it only when the JSON exists).
4. Rebuild with npm run cap:build:android.
5. Ensure POST_NOTIFICATIONS, RECORD_AUDIO, MODIFY_AUDIO_SETTINGS, CAMERA, and foreground-service permissions are granted on Android 13+.
6. Verify MobilePushRegistrationService logs a registration token after login.

Android runtime permissions (voice / camera)

Capacitor's WebView requests RECORD_AUDIO and MODIFY_AUDIO_SETTINGS together for microphone capture. If MODIFY_AUDIO_SETTINGS is missing from AndroidManifest.xml, users can accept the prompt and getUserMedia still fails.

Declared in toju-app/android/app/src/main/AndroidManifest.xml:

Permission	Purpose
RECORD_AUDIO	Microphone capture for voice calls and channels
MODIFY_AUDIO_SETTINGS	Required by Capacitor WebChromeClient alongside RECORD_AUDIO
CAMERA	WebRTC camera sharing and WebView file capture
BLUETOOTH_CONNECT	Bluetooth headset routing during calls (Android 12+)
POST_NOTIFICATIONS	Incoming/active call notifications
FOREGROUND_SERVICE / FOREGROUND_SERVICE_MICROPHONE	Background voice session

Before WebRTC capture, the client calls MobileMediaService.ensureVoiceCapturePermissions() / ensureCameraCapturePermissions(), which delegate to MetoyouMobile.requestVoiceCapturePermissions() / requestCameraCapturePermissions() on Capacitor shells. If the native plugin is unavailable or the bridge call fails, capture preflight defers to the WebView getUserMedia permission flow instead of aborting voice/camera joins.

On Capacitor startup, MobileRuntimePermissionsService (via MobileAppLifecycleService.initialize()) proactively prompts for microphone, camera, local-notification, and push-notification runtime permissions so Android 13+ shells do not keep every permission in the "Not allowed" state until the user joins voice or receives a call.

iOS (APNs)

1. Enable Push Notifications capability in Xcode for the App target.
2. Upload your APNs key/certificate in Apple Developer portal.
3. Info.plist includes remote-notification, audio, and voip background modes.
4. Run on a physical device; simulator push registration is limited.

Server token storage & dispatch

Clients POST:

POST /api/users/device-tokens
Content-Type: application/json

{ "userId": "<uuid>", "platform": "android|ios", "token": "<fcm-or-apns-token>" }

Tokens persist in server SQLite (device_tokens table). Outbound push uses repository-root .env credentials:

Variable	Purpose
FCM_SERVICE_ACCOUNT_PATH or FCM_SERVICE_ACCOUNT_JSON	Android FCM HTTP v1
APNS_KEY_PATH, APNS_KEY_ID, APNS_TEAM_ID	iOS APNs HTTP/2
APNS_BUNDLE_ID	Defaults to com.metoyou.app
APNS_USE_SANDBOX	true for development builds

Manual dispatch (ops/testing):

POST /api/users/device-tokens/:userId/dispatch
{ "title": "Incoming call", "body": "Alice is calling" }

Android foreground service

VoiceCallForegroundService starts when MobileCallSessionService begins an active call. Required manifest permissions:

• FOREGROUND_SERVICE
• FOREGROUND_SERVICE_MICROPHONE
• RECORD_AUDIO
• MODIFY_AUDIO_SETTINGS
• POST_NOTIFICATIONS

The service shows a low-importance ongoing notification while a call is active.

SQLite persistence (Capacitor)

• Schema rules: infrastructure/mobile/logic/mobile-sqlite-schema.rules.ts (mirrors Electron entities).
• Statement execution: infrastructure/mobile/logic/mobile-sqlite-execute.rules.ts — @capacitor-community/sqlite execute() accepts one SQL statement per call; migrations run each DDL statement separately (never concatenated).
• Row mapping: infrastructure/mobile/logic/mobile-sqlite-row-mapper.rules.ts.
• CRUD service: infrastructure/persistence/capacitor-database.service.ts.
• Routing: infrastructure/persistence/database-backend.rules.ts — Capacitor uses SQLite, not IndexedDB.
• Per-user database files: metoyou__<userId> via mobile-sqlite-database-name.rules.ts.
• First launch runs DDL migrations stored in the meta table. Schema init failures are cached per database file so the client does not retry in a loop.

Capacitor plugin loading

• infrastructure/mobile/adapters/capacitor/capacitor-plugin-loader.ts uses static @capacitor/* imports and Capacitor.isPluginAvailable() before returning a plugin. Do not import() plugin modules dynamically or await plugin objects (Capacitor proxies expose a throwing .then() stub).
• After adding or upgrading Capacitor plugins, run npm run build:prod && npm run cap:sync so Android/iOS native projects register App, AppUpdate, LocalNotifications, push, and SQLite.

Safe area (Android)

• Capacitor SystemBars injects --safe-area-inset-* CSS variables into document.documentElement. index.html sets viewport-fit=cover and default inset values; main.ts calls applyMobileSafeAreaDefaults() so injection never hits a missing root element after the WebView loads.
• capacitor.config.ts sets plugins.SystemBars.insetsHandling: 'css' so Android WebView versions that mis-report env(safe-area-inset-*) still receive correct insets.
• Global styles.scss applies inset padding on html (with env() fallback) and sizes app-root to height: 100% so content stays below the status bar and above the navigation bar in edge-to-edge mode.

Self-hosted HTTPS signal servers (Android)

Electron and desktop browsers accept the repo's self-signed .certs/localhost.crt because Electron runs with ignore-certificate-errors when SSL=true, and browsers let users bypass the warning once. Android WebView does neither — it only trusts system CAs (release) or system + user-installed CAs (debug builds).

Runtime	Trust behavior
Electron (SSL=true)	Ignores certificate errors (electron/app/flags.ts)
Browser	User accepts warning or imports CA
Android debug APK	System CAs + user-installed CAs (src/debug/res/xml/network_security_config.xml)
Android release APK	System CAs only — use Let's Encrypt or another public CA

Certificate requirements

1. Trust: Install .certs/localhost.crt on the Android device as a CA certificate (Settings → Security → Encryption & credentials → Install a certificate → CA certificate). Debug APKs pick this up automatically; release builds ignore user CAs.

2. SAN: The cert must list every host clients use. Regenerate with the server IP in the SAN when connecting by IP:

   rm -rf .certs
   SERVER_IP=46.59.68.77 ./generate-cert.sh
   

   Restart the signaling server after regenerating certs.

3. HTTPS only: AndroidManifest.xml sets android:usesCleartextTraffic="false". Server URLs must use https:// (matching environment.ts / saved server endpoints).

Troubleshooting

Symptom	Likely cause
ERR_CERT_AUTHORITY_INVALID / silent fetch failure	CA not installed on device, or testing a release APK with a self-signed cert
ERR_CERT_COMMON_NAME_INVALID	Cert SAN missing the IP/hostname (regenerate with SERVER_IP)
ERR_CONNECTION_REFUSED	Port unreachable from the phone (firewall, NAT, server not listening on 0.0.0.0) — verify with curl -k https://46.59.68.77:3001/api/health from the device browser first
Works in Chrome on phone, fails in app	Chrome may use a different trust store path; ensure the CA is installed at the system level, not only per-browser

Network security configs:

• android/app/src/main/res/xml/network_security_config.xml — release (system CAs, no cleartext)
• android/app/src/debug/res/xml/network_security_config.xml — debug (+ user CAs for dev)

Do not commit .certs/*.crt, .certs/*.key, or device-specific credential files.

Integration points

• DirectCallService — incoming/active call notifications, ring-queue on user hydration, notification action routing.
• PrivateCallComponent — speakerphone toggle on native mobile shells.
• ChatMessageComposerComponent — shouldShowAttachmentButton + pickAttachmentsFromDevice().
• VoiceWorkspaceStreamTileComponent — PiP when focused stream tile backgrounds.
• MobileCallSessionService — CallKit + foreground service + in-call notifications.
• App bootstrap — initializes mobile persistence, lifecycle, app-update polling, call-session, and push registration wiring.
• MobileAppUpdateService — periodic Play Store / App Store checks (30 min) and settings UI actions; mirrors Electron DesktopAppUpdateService polling but uses native store APIs instead of release manifests.

Phase 3 completion notes

Phase 3 delivered:

1. Full CapacitorDatabaseService CRUD with DatabaseService routing on isCapacitor.
2. Server SQLite persistence for device tokens plus FCM/APNs outbound dispatch.
3. iOS CallKit bridge (partial) via MetoyouMobile plugin and MobileCallKitService.
4. Android Firebase Gradle wiring with google-services.json.example (real file gitignored).
5. Capacitor plugin availability checks to avoid hard failures when plugins are missing pre-sync.
6. Discovery endpoint skip for production signal hosts without featured/trending routes.

Remaining work:

• Wire CallKit answer/end actions back into DirectCallService.
• Migrate legacy IndexedDB mobile data into SQLite where needed.
• Deploy featured/trending routes to production signal servers or add capability negotiation in health checks.