pikebacker/docs/03_system_architecture.md

System Architecture

Recommended stack

Apps

• apps/web: trip planning interface.
• apps/mobile: mobile riding/offline interface.

Recommended technologies:

• TypeScript.
• React for web.
• React Native for mobile.
• MapLibre-compatible rendering.

Backend

• API service: FastAPI or equivalent.
• Database: PostgreSQL + PostGIS.
• Queue: Redis + worker for imports/scoring/offline-pack jobs.
• Object storage: S3-compatible bucket for generated exports/offline manifests.

Routing

Routing must be accessed through a provider interface. Supported target providers:

• openrouteservice for prototype/API-based routing,
• GraphHopper for self-hosted or API routing,
• Valhalla for self-hosted routing and isochrones,
• BRouter-inspired offline routing later.

Map display

• MapLibre-compatible client.
• Vector tiles from self-hosted OpenMapTiles, Protomaps/PMTiles, MapTiler, or equivalent.
• Do not rely on public OSM tile servers for production app traffic.

Data pipeline

Pipeline jobs:

1. Download OSM extracts.
2. Normalize bikepacking-relevant tags.
3. Build route graph or send extract to routing engine.
4. Import POIs.
5. Attach elevation.
6. Import protected areas/rules.
7. Generate derived segment scores.
8. Build offline pack manifests.

Services

Client Apps
  |-- Web planner
  |-- Mobile rider app

Backend API
  |-- Auth/session
  |-- Trip planner
  |-- Stage planner
  |-- Route scorer
  |-- POI corridor service
  |-- Offline pack service
  |-- Export service
  |-- Community report service
  |-- Rules service

Provider Layer
  |-- Routing provider
  |-- Elevation provider
  |-- POI provider
  |-- Weather provider
  |-- Accommodation provider
  |-- Device export provider

Data Stores
  |-- PostGIS
  |-- Object storage
  |-- Cache/queue

Provider interfaces

Every external dependency should be swappable.

interface RoutingProvider {
  planRoute(request: RoutePlanRequest): Promise<RouteGeometryResult>;
  reroute(request: RerouteRequest): Promise<RouteGeometryResult>;
}

interface PoiProvider {
  searchCorridor(request: CorridorPoiRequest): Promise<Poi[]>;
}

interface ElevationProvider {
  samplePolyline(polyline: Coordinate[]): Promise<ElevationSample[]>;
}

interface WeatherProvider {
  forecastAlongRoute(request: WeatherRouteRequest): Promise<RouteWeatherRisk[]>;
}

interface RulesProvider {
  getRuleCards(request: RuleCardRequest): Promise<RuleCard[]>;
}

MVP architecture simplification

For first implementation:

• use a hosted routing provider or mock routing fixture;
• use OSM-derived POI fixtures in PostGIS;
• implement stage planning and scoring locally;
• render a route and stage cards;
• export GPX;
• define offline pack manifest without full tile download implementation.