Alpha stage commit

docs/03_system_architecture.md

@@ -0,0 +1,120 @@
+# 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
+
+```text
+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.
+
+```ts
+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.