trails-cool/trails
1
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
trails/openspec/changes/mobile-app/specs/mobile-journal-client/spec.md
Ullrich Schäfer fff77a2ed2
Add mobile app, map-core, nearby sync, and activity recording specs 
mobile-app: Unified React Native + Expo app combining Planner and
Journal. OAuth2 PKCE auth, MapLibre maps, versioned REST API with
Zod schemas, configurable server URL, offline SQLite, Web Push relay
notifications. TanStack Query + Zustand state management. Jest +
Maestro testing. 76 tasks across 5 phases.

map-core-package: Extract renderer-agnostic map definitions (tiles,
color palettes, POI categories, z-index) into @trails-cool/map-core.
Pure refactor preparing for MapLibre on mobile. 27 tasks.

mobile-activity-recording: GPS recording, live stats, HealthKit/Health
Connect export. Separated from mobile-app for independent scheduling.

mobile-nearby-sync: BLE route sync between nearby devices for offline
group riding. QR waypoint sharing as simpler v1. TXQR noted as future.

journal-rest-api spec: Full API contract — endpoints, auth, pagination,
errors, discovery, versioning, BRouter proxy.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-12 21:52:30 +02:00

2.2 KiB
Raw Blame History

ADDED Requirements

Requirement: Journal authentication client

The system SHALL provide an API client that handles OAuth2 PKCE authentication with a Journal instance.

Scenario: Login flow

  • WHEN the user enters their Journal instance URL and taps "Sign in"
  • THEN the app opens the Journal's /oauth/authorize endpoint in an in-app browser, receives the auth code on redirect, and exchanges it for access + refresh tokens

Scenario: Token storage

  • WHEN tokens are received from the Journal
  • THEN the access token and refresh token are stored in Expo SecureStore

Scenario: Token refresh

  • WHEN an API request fails with a 401
  • THEN the client automatically uses the refresh token to obtain a new access token and retries the request

Requirement: Routes API client

The system SHALL provide methods for listing, fetching, creating, and updating routes on the Journal.

Scenario: List user routes

  • WHEN the Routes tab is opened
  • THEN the client fetches the user's routes from GET /api/routes and returns them as typed Route objects

Scenario: Fetch route detail

  • WHEN a route is selected
  • THEN the client fetches the route with GPX data from GET /api/routes/:id including waypoints and geometry

Scenario: Save route

  • WHEN the user saves an edited route
  • THEN the client sends the updated GPX to PUT /api/routes/:id and returns the new version

Requirement: Activities API client

The system SHALL provide methods for listing, fetching, and creating activities on the Journal.

Scenario: List user activities

  • WHEN the Activities tab is opened
  • THEN the client fetches the user's activities from GET /api/activities

Scenario: Create activity

  • WHEN a recording is saved
  • THEN the client sends the activity data (GPX, distance, duration, routeId) to POST /api/activities

Requirement: Network error handling

The system SHALL handle network failures gracefully across all API calls.

Scenario: Request timeout or network error

  • WHEN an API request fails due to network issues
  • THEN the client returns a typed error and the UI shows an appropriate message with a retry option