trails/openspec/changes/mobile-app/design.md

Context

trails.cool is a two-app web platform: Planner (stateless, collaborative, Yjs) and Journal (accounts, PostgreSQL, ActivityPub). The Planner uses Leaflet for maps, Yjs for real-time sync, and BRouter for routing. The Journal stores routes, activities, and user data. Shared packages (types, gpx, i18n) are pure TypeScript.

The mobile app combines both apps into a single React Native + Expo experience, communicating with the Journal as its backend. The user is an experienced React Native/Expo developer.

Goals / Non-Goals

Goals:

• Unified mobile app (plan + journal in one)
• Authenticate with existing Journal account
• View and edit routes on the go
• Record GPS activities
• Work offline for viewing routes
• Reuse shared TypeScript packages

Non-Goals:

• Full collaborative Yjs editing on mobile (too complex for v1 — use direct API)
• Self-hosting the mobile app (App Store distribution only)
• Replacing the web Planner (mobile editing is simplified)
• ActivityPub federation from mobile (handled by Journal server)
• Offline route computation (BRouter requires server)

Decisions

D1: Expo managed workflow with monorepo integration

Place the app at apps/mobile/ in the existing pnpm monorepo. Use Expo managed workflow (no native code ejection) with EAS Build for CI/CD. Share packages via pnpm workspace — @trails-cool/types, @trails-cool/gpx, @trails-cool/i18n imported directly.

The gpx package uses linkedom for Node.js XML parsing. On mobile, use the built-in DOMParser (available in React Native's JSC/Hermes via a polyfill or the existing browser code path in parseGpx).

D2: Authentication via OAuth2 PKCE

The Journal currently uses passkeys + magic links. Neither works well in a native app context. Add an OAuth2 authorization code flow with PKCE to the Journal:

• Mobile app opens Journal's /oauth/authorize in an in-app browser
• User authenticates via existing passkey/magic link
• Journal redirects back with auth code
• Mobile app exchanges code for access + refresh tokens
• Tokens stored in Expo SecureStore

This keeps the auth UI on the web (no need to implement passkey in native code) while giving the mobile app long-lived tokens.

The mobile app sends a device name (e.g., model + OS version) during token exchange. The Journal stores this alongside the token, enabling a "Connected Devices" list on the Journal web settings page where users can see active sessions and revoke individual devices. This is primarily relevant for the hosted version — self-hosted instances with a single user would rarely use it, but the data is stored regardless.

D2b: Configurable server URL

The mobile app defaults to https://trails.cool but allows connecting to any self-hosted Journal instance. On the login screen, a "Connect to a different server" option lets the user enter a custom URL (e.g., https://trails.example.org). The app validates the URL by fetching /.well-known/trails-cool (or a similar discovery endpoint) to confirm it's a compatible instance.

The server URL is stored persistently and used as the base for all API calls and the OAuth2 login flow. Users can switch instances from the Profile tab — this logs them out and clears local data.

The /.well-known/trails-cool discovery endpoint returns an apiVersion semver string (e.g., "1.0.0"). The mobile app declares a requiredApiVersion (minimum semver it needs). On connect and on app foreground, the app checks:

• Server apiVersion satisfies app's required range → normal operation.
• Server apiVersion too low → Block: "This server needs to be updated. Please ask the administrator to upgrade." The app still allows read-only access to cached offline data.

The API follows semver: patch versions for fixes, minor versions for additive changes (new endpoints, new optional fields), major versions only for breaking changes. Since the API is backwards compatible by design, a newer server always works with an older app — no "server too new" check needed.

D2c: Shared API contract package

A new packages/api/ workspace package (@trails-cool/api) serves as the single source of truth for the REST API:

• API_VERSION constant (semver string)
• TypeScript types for all request/response shapes (e.g., RouteListResponse, CreateActivityRequest)
• Endpoint path constants (e.g., ENDPOINTS.routes.list = "/api/v1/routes")
• Error response type

The package uses Zod schemas as the source of truth — TypeScript types are inferred via z.infer<>. The Journal server uses schemas to validate incoming request bodies. The mobile client can optionally validate responses (useful for self-hosted instances on older versions). Both sides share the same schemas — runtime validation and type safety from one definition.

D3: MapLibre GL for mobile maps

Leaflet is web-only. Use react-native-maplibre-gl for mobile — OSM vector tiles, GPU-accelerated, free, consistent with the web's OSM data source. Requires an Expo config plugin but is well-supported.

The web Planner stays on Leaflet for now, but map logic should be structured for future convergence:

• @trails-cool/map-core (new package): Renderer-agnostic definitions — tile source URLs, overlay configs, color palettes (route coloring, POI categories), z-index layering order. Pure data, no rendering code.
• @trails-cool/map (existing): Leaflet-specific components for web, imports from map-core
• apps/mobile/: MapLibre-specific components for mobile, imports from map-core

This way, switching the web to MapLibre later means replacing @trails-cool/map internals while map-core stays unchanged. The mobile app validates that map-core abstractions work before the web migration.

D4: Simplified route editing (no Yjs)

Mobile route editing talks directly to the Journal API:

1. Fetch route GPX → parse waypoints
2. User adds/moves/deletes waypoints on the map
3. Compute route via BRouter (through a proxy endpoint on the Journal, or direct to the Planner's BRouter instance)
4. Save updated GPX back to Journal API

No real-time collaboration on mobile. If the user needs full collaborative editing, deep-link to the Planner web app.

D5: Offline with SQLite + tile cache

• Routes: Download GPX + parsed waypoints into Expo SQLite
• Map tiles: Use react-native-maps' built-in tile caching, or download tile packages for specific regions
• Activities: Stored locally first, synced to Journal when online
• Edit queue: Changes made offline queued and synced on reconnect (conflict resolution: last-write-wins, with a warning if the server version changed)

D6: Activity recording

Activity recording (GPS tracking, HealthKit) is a separate change — see mobile-activity-recording.

D7: Navigation structure

Tab bar with 4 tabs:

• Map: Current route on map, quick edit, start recording
• Routes: List of user's routes from Journal
• Activities: List of recorded activities
• Profile: Account settings, offline data management, sync status

D8: BRouter routing via Journal API proxy

The mobile app computes routes through the Journal API: POST /api/v1/routes/compute. The Journal forwards the request to its BRouter instance and returns the enriched route. This avoids exposing BRouter publicly and works with self-hosted instances where the BRouter container isn't publicly accessible.

D9: Photo uploads via presigned URLs

Route and activity photos are stored in S3/Garage (existing infrastructure). The API returns presigned upload URLs — the mobile app uploads directly to storage, then confirms the upload via the API. This avoids proxying large files through the Journal server.

D10: Cursor-based pagination

All list endpoints (routes, activities) use cursor-based pagination. The response includes a nextCursor field — the client passes it back to get the next page. This handles feeds that change (new items, deletions) without skipping or duplicating entries.

D11: Expo monorepo support

Use Expo's built-in experiments.monorepo: true in app.config.ts to resolve pnpm workspace packages in Metro. This handles symlink resolution and shared package discovery automatically.

D12: Push notifications via Web Push relay

Following Mastodon's proven architecture for federated push notifications:

• Journal instances implement standard Web Push API (RFC 8030) — no Apple/Google dependencies on the server side
• trails.cool hosts a relay service that translates Web Push → APNs (iOS) and FCM (Android). Self-hosted instances send standard Web Push to this relay.
• Notifications are end-to-end encrypted — the relay forwards encrypted payloads without reading them
• Self-hosted admins need zero configuration — no Apple Developer account, no Firebase project. Standard Web Push just works.
• The relay is open-source — self-hosters who want full independence can run their own relay with their own APNs/FCM credentials

Flow: Journal instance → Web Push (encrypted) → trails.cool relay → APNs/FCM → phone

This aligns with the ActivityPub federation direction and matches how Mastodon clients (Toot!, Ice Cubes, etc.) handle push for thousands of self-hosted instances through a single relay.

D13: State management

Three layers, each with a clear responsibility:

• TanStack Query for server state — routes, activities, user profile. Provides caching, background refetch, stale-while-revalidate, cursor pagination helpers, and optimistic updates. All Journal API data flows through TanStack Query hooks.
• Zustand for local UI state — edit mode flags, recording state, offline queue status, selected map layer, download progress. Small, synchronous stores with no persistence (or optional persistence to AsyncStorage where needed).
• React Context only for auth token and server URL — these are set once at login and consumed everywhere. No complex state, no frequent updates. Avoids prop drilling for the two values every API call needs.

D14: Tile hosting

MapLibre needs a vector tile source. Default to OpenFreeMap — free, OSM-based, no API key required. This matches the project's principle of using open standards and avoiding vendor lock-in.

Self-hosted instances can configure a custom tile URL in the discovery endpoint. The /.well-known/trails-cool response gains a tileUrl field (e.g., "tileUrl": "https://tiles.example.org/{z}/{x}/{y}.pbf"). When present, the mobile app and any future MapLibre web client use it instead of the default.

Fallback: if vector tiles fail to load (offline, misconfigured URL), fall back to raster tiles from OpenStreetMap tile servers — the same approach the web Planner already uses with Leaflet.

D15: Photo/media handling

Routes and activities can have photos. The upload flow avoids proxying large files through the Journal server:

1. Client requests a presigned upload URL from POST /api/v1/uploads with filename and content type
2. Client uploads the file directly to S3/Garage using the presigned URL
3. Client confirms the upload via the API with the storage key (e.g., POST /api/v1/routes/:id or PUT /api/v1/routes/:id with the storage key in the photos array)

Photos are stored as an array of URLs on the route or activity record. Thumbnails are generated server-side on upload confirmation — the Journal creates a resized version and stores it alongside the original. The API returns both url and thumbnailUrl for each photo.

D16: Journal REST API implementation

The REST API endpoints (/api/v1/*) are implemented as React Router route modules under apps/journal/app/routes/api.v1.*.ts. This follows the existing routing pattern — both apps use explicit routes.ts for registration.

Shared middleware handles:

• Bearer token validation: Extracts and validates the OAuth2 access token from the Authorization header, attaches the authenticated user to the request context
• Zod body parsing: Validates request bodies against schemas from @trails-cool/api, returns structured 400 errors on failure
• Error formatting: Catches exceptions and returns the standard ApiErrorResponse shape

Existing web routes (cookie-based auth, form actions, loaders) remain unchanged. The /api/v1/* routes use bearer tokens exclusively — no cookie sessions.

Risks / Trade-offs

• BRouter access from mobile: The BRouter instance runs in Docker alongside the Planner. The mobile app needs a route computation endpoint. Options: (a) proxy through Journal API, (b) expose BRouter publicly with auth, (c) use a public BRouter instance. Option (a) is safest.
• Map tile licensing: Google Maps requires an API key and has usage-based pricing. Apple Maps is free on iOS. Consider MapLibre with OpenStreetMap tiles for a free, consistent cross-platform solution.
• React Native Maps vs MapLibre: react-native-maps is more mature but ties to Google/Apple. react-native-maplibre-gl uses vector tiles and is more consistent with the web's OSM-based approach. Worth evaluating.
• Offline storage size: Map tiles for a region can be hundreds of MB. Need a download manager with progress and storage budget.
• App Store review: GPS background tracking + health data access need careful privacy descriptions.