pikebacker/codex/IMPLEMENTATION_TASKS.md

Implementation Tasks for Codex

Task 1 — Create monorepo scaffold

Create:

apps/web
apps/mobile
services/api
services/data-pipeline
packages/shared

Acceptance criteria:

• root package/workspace or equivalent created;
• lint/test scripts documented;
• shared domain types imported by web/API where applicable;
• .env.example files created;
• no API keys committed.

Task 2 — Implement shared domain types and scoring

Implement TypeScript types from schemas/domain_types.ts.

Add pure functions:

• scoreSegment(segment, profile);
• scoreRoute(route, profile);
• detectCriticalGaps(route, pois, thresholds);
• estimateHikeABikeRisk(segment, profile).

Acceptance criteria:

• unit tests pass;
• sample scoring fixture returns expected warnings;
• profile thresholds are configurable.

Task 3 — Backend API mock MVP

Implement endpoints from schemas/openapi.yaml with mock data:

• POST /v1/routes/plan,
• POST /v1/stages/plan,
• GET /v1/routes/{id}/pois,
• GET /v1/routes/{id}/gaps,
• POST /v1/offline-packs,
• GET /v1/routes/{id}/export?format=gpx,
• POST /v1/reports.

Acceptance criteria:

• returns deterministic responses from examples/;
• API validation is implemented;
• tests cover success and error cases.

Task 4 — Stage planner

Implement stage splitting:

• respect min/max daily distance;
• prefer endpoints near sleep options;
• avoid long water/food gaps at stage end;
• include Plan A/B endpoints;
• generate warnings.

Acceptance criteria:

• 3-day and 5-day fixture routes produce plausible stages;
• no stage exceeds hard constraints unless warning returned;
• sleep candidates attached to each stage.

Task 5 — Web planner UI

Build a web UI:

• trip request form;
• map panel;
• stage timeline;
• POI filter toggles;
• warnings panel;
• export/offline buttons.

Acceptance criteria:

• user can submit sample trip and see route/stages;
• route-corridor POIs shown/listed;
• critical warnings visible;
• GPX export downloads.

Task 6 — GPX export

Generate valid GPX with:

• route geometry;
• waypoints for stage endpoints;
• optional POIs/course points;
• metadata and attribution.

Acceptance criteria:

• validates as XML;
• imports into common route viewers;
• includes stage waypoints.

Task 7 — Offline pack manifest

Implement offline manifest generation.

Acceptance criteria:

• includes route, stages, POIs, rules, exports, data versions;
• marks unavailable layers clearly;
• supports future tile pack file references.

Task 8 — Data pipeline skeleton

Implement scripts/docs for:

• reading OSM PBF extract;
• extracting POI categories;
• normalizing tags;
• inserting into PostGIS;
• importing protected areas/rule cards later.

Acceptance criteria:

• one small sample extract/fixture works;
• schema migrations documented;
• source attribution stored.

Task 9 — Provider adapters

Add adapters:

• mock routing provider;
• openrouteservice provider placeholder;
• GraphHopper/Valhalla adapter interfaces;
• OSM POI provider.

Acceptance criteria:

• provider selected via environment/config;
• mock provider is default;
• external provider failures return actionable errors.

Task 10 — Community reports

Implement structured report model and UI submission.

Acceptance criteria:

• reports typed and dated;
• offline queue represented;
• reports can attach to route meters/location;
• moderation status supported.