compassmock/docs/modules/mobile.md

Mobile Module

The mobile module wraps Compass in a native iOS and Android app using Capacitor. It's not a separate codebase or a React Native port -- it's a WebView that loads the live Cloudflare deployment. The native layer adds device-specific capabilities: biometric authentication, push notifications, camera access with GPS tagging, offline photo queuing, and status bar theming.

The fundamental design principle: the web app must never break because of native code. Every Capacitor import is dynamic (await import()), every native feature is gated behind isNative() checks, and every native component returns null on web. If Capacitor isn't present, the app works exactly as it does in a browser.

platform detection

src/lib/native/platform.ts provides the detection layer. It checks for the Capacitor global that the native runtime injects before hydration:

function getCapacitor(): CapacitorGlobal | undefined {
  if (typeof window === "undefined") return undefined
  return (window as unknown as Record<string, unknown>)
    .Capacitor as CapacitorGlobal | undefined
}

export function isNative(): boolean {
  return getCapacitor()?.isNative ?? false
}

export function isIOS(): boolean {
  return getCapacitor()?.getPlatform() === "ios"
}

export function isAndroid(): boolean {
  return getCapacitor()?.getPlatform() === "android"
}

The key detail: isNative() returns false on the server (no window), false in a normal browser (no Capacitor global), and true only in the native WebView. This three-way distinction matters for SSR -- server-rendered HTML assumes web, and the native state is only known after hydration.

There's also src/lib/native/detect-server.ts for server-side detection via User-Agent:

export function isNativeApp(request: Request): boolean {
  const ua = request.headers.get("user-agent") ?? ""
  return ua.includes("CapacitorApp")
}

the useNative hook

src/hooks/use-native.ts wraps platform detection in a React hook using useSyncExternalStore. The snapshot never changes after initial load (Capacitor injects before hydration), so the hook is stable.

export function useNative(): boolean {
  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot)
}

getServerSnapshot returns false (SSR assumes web). getSnapshot returns isNative(). The subscribe function is a no-op because the value never changes after mount.

Every native feature checks useNative() before attempting to load Capacitor plugins. This is the gate that prevents web breakage.

native hooks

Each native capability has its own hook:

use-native-push.ts -- push notification registration. On mount (if native), requests notification permissions, registers with APNS/FCM, listens for token registration events, and POSTs the token to /api/push/register. Also handles foreground notifications and deep-linking when a notification is tapped.

const actionListener = await PushNotifications.addListener(
  "pushNotificationActionPerformed",
  (action) => {
    const url = action.notification.data?.url
    if (typeof url === "string" && url.startsWith("/")) {
      router.push(url)
    }
  },
)

use-native-camera.ts -- camera access with EXIF extraction. Captures photos at 85% quality, 2048px width, saves to gallery, extracts GPS coordinates and timestamp from EXIF data.

use-biometric-auth.ts -- Face ID / fingerprint authentication. Checks device capability on mount, manages enabled/prompted state in localStorage, provides authenticate() that calls NativeBiometric.verifyIdentity. The biometric lock activates after the app has been backgrounded for 30+ seconds.

use-photo-queue.ts -- the most complex hook. Combines camera capture with offline-resilient upload. Takes a photo, saves it to the device filesystem, adds metadata to the queue, and auto-uploads when connectivity returns. Listens for network state changes via @capacitor/network.

const takeAndQueuePhoto = useCallback(
  async (projectId: string): Promise<CapturedPhoto | null> => {
    const photo = await takePhoto()
    if (!photo) return null
    const id = nanoid()
    const fileName = `${id}.${photo.format}`
    const localPath = await savePhotoToDevice(photo.uri, fileName)
    await addToQueue({
      id, projectId, localPath, fileName,
      lat: photo.exifData.lat, lng: photo.exifData.lng,
      capturedAt: new Date().toISOString(),
    })
    await refresh()
    return photo
  },
  [takePhoto, refresh],
)

offline photo queue

src/lib/native/photo-queue.ts is the persistence layer for photos captured on jobsites with spotty connectivity. It uses Capacitor's Preferences plugin (key-value storage that survives app kill) to track queue metadata, and the Filesystem plugin to store actual photo files in the app's data directory.

The queue lifecycle:

1. Capture: Photo is taken, copied to compass-photos/{id}.{format} in the app's data directory
2. Queue: Metadata (project ID, GPS coords, timestamp, file path) added to the queue with pending status
3. Upload: When online, processQueue() iterates pending items, uses @capgo/capacitor-uploader to POST each file with metadata headers
4. Cleanup: Successfully uploaded photos are deleted from the filesystem and removed from the queue
5. Retry: Failed uploads get retried up to 3 times. After that, they stay in failed status until manually retried

await Uploader.startUpload({
  filePath: photo.localPath,
  serverUrl: uploadUrl,
  method: "POST",
  headers: {
    "X-Project-Id": photo.projectId,
    "X-Photo-Id": photo.id,
    "X-Captured-At": photo.capturedAt,
    ...(photo.lat !== undefined && { "X-GPS-Lat": String(photo.lat) }),
    ...(photo.lng !== undefined && { "X-GPS-Lng": String(photo.lng) }),
  },
})

GPS coordinates and timestamps are passed as headers rather than multipart form fields. This keeps the upload simple (single file body) while preserving all metadata.

native components

src/components/native/ contains four components. All return null on web.

native-shell.tsx -- syncs the native status bar style with the current theme. When the app switches between light and dark mode, the status bar text color updates to match.

export function NativeShell() {
  const native = useNative()
  const { resolvedTheme } = useTheme()

  useEffect(() => {
    if (!native) return
    async function syncStatusBar() {
      const { StatusBar, Style } = await import("@capacitor/status-bar")
      await StatusBar.setStyle({
        style: resolvedTheme === "dark" ? Style.Dark : Style.Light,
      })
    }
    syncStatusBar()
  }, [native, resolvedTheme])

  return null
}

biometric-guard.tsx -- wraps the app with biometric lock screen functionality. Listens for app state changes (background/foreground). If the app was backgrounded for more than 30 seconds and biometrics are enabled, it shows a full-screen lock overlay. Auto-authenticates on appear, with a fallback "Use password" button that redirects to the login page.

Also handles first-login setup: after a 2-second delay on first native launch, prompts the user to enable biometric locking. The prompt state is tracked in localStorage so it's only shown once.

offline-banner.tsx -- shows a slim amber banner when the device is offline. Uses @capacitor/network on native, falls back to navigator.onLine events on web. This component actually works on both platforms -- the web fallback is useful for PWA-like behavior.

upload-queue-indicator.tsx -- shows pending photo upload count as a pill badge. Changes appearance based on status: neutral for pending, pulsing for uploading, red for errors with "tap to retry" text.

push notifications

src/lib/push/send.ts sends push notifications via FCM HTTP v1 API. It works from Cloudflare Workers without the Firebase SDK -- just a direct HTTP POST to https://fcm.googleapis.com/v1/projects/-/messages:send.

The sender:

1. Looks up all push tokens for the target user from the push_tokens table
2. Sends each token a notification with platform-specific config (high priority for Android, sound + badge for iOS)
3. Auto-cleans invalid tokens: 404 responses (unregistered device) trigger token deletion

const message: FcmMessage = {
  message: {
    token: t.token,
    notification: { title: payload.title, body: payload.body },
    data: payload.data ? { ...payload.data } : undefined,
    android: { priority: "high" },
    apns: { payload: { aps: { sound: "default", badge: 1 } } },
  },
}

Device tokens are registered via POST /api/push/register (called by use-native-push.ts on app launch) and cleaned up via DELETE /api/push/register.

Capacitor configuration

capacitor.config.ts configures the native wrapper:

const config: CapacitorConfig = {
  appId: "ltd.openrangeconstruction.compass",
  appName: "Compass",
  webDir: "public",
  server: {
    url: "https://compass.openrangeconstruction.ltd",
    cleartext: false,
    allowNavigation: [
      "compass.openrangeconstruction.ltd",
      "api.workos.com",
      "authkit.workos.com",
      "accounts.google.com",
      "login.microsoftonline.com",
    ],
  },
}

The server.url points to the live production deployment. The app doesn't bundle a static export -- it loads the real web app in a WebView. This means native users always get the latest version without app store updates for UI changes.

allowNavigation lists domains the WebView is allowed to navigate to. This is needed for OAuth flows (WorkOS, Google, Microsoft) that redirect the user to external auth pages.

The webDir: "public" is mostly a formality for Capacitor CLI requirements. Since the app loads from a remote URL, local web assets are only used during the splash screen.

Plugins configured:

• SplashScreen -- white background, 2-second display, auto-hide
• Keyboard -- resize body on keyboard show (not viewport), dark style
• PushNotifications -- badge, sound, and alert presentation options

iOS-specific: contentInset: "automatic" for safe area handling, custom compass URL scheme. Android-specific: mixed content disabled (HTTPS only), input capture enabled.

the dynamic import pattern

Every Capacitor plugin is loaded with dynamic await import() inside an async function, never at module scope. This is critical: Capacitor plugins only exist in the native runtime. A top-level import would crash the web app at module evaluation time.

// correct: dynamic import inside a native-gated effect
useEffect(() => {
  if (!native) return
  async function setup() {
    const { PushNotifications } = await import("@capacitor/push-notifications")
    await PushNotifications.requestPermissions()
  }
  setup()
}, [native])

This pattern repeats throughout the mobile module. The native check prevents the import from even being attempted on web, and the dynamic import ensures the module is only loaded when actually needed.