trails/openspec/changes/route-surface-breakdown/design.md

Context

The Planner computes accurate per-coordinate surface/highway from BRouter's messages/WayTags (apps/planner/.../route-merge.ts → EnrichedRoute), and ColoredRoute already renders the route coloured by surface. But this metadata is session-only: the planner→journal handoff (api.save-to-journal) POSTs only { gpx } to the Journal callback (api.routes.$id.callback), the routes table has no surface column, and GPX carries no surface extensions. So today no saved route has surface data.

Goals / Non-Goals

Goals

• Surface + waytype proportion bars on route detail, using data we already compute, with no new external dependency.

Non-Goals (v1)

• Activities / imported / manually-uploaded GPX — they have no waytags (bare GPX). They show no breakdown for now (see "Data source" → future Overpass).
• Colouring the Journal map line by surface — needs per-segment data, not just the summary; a clean follow-up once the bars land.
• Selectable surface-vs-waytype toggle UI beyond showing both bars.

Decisions

D1: Data source — persist BRouter waytags at save (Planner routes only)

Two ways to get a breakdown onto the Journal detail page:

• (A, chosen) BRouter-at-save — the Planner already has 100%-accurate per-segment surface/highway; compute the distribution there at save and persist it. Accurate, cheap, no external call. Limitation: only Planner-created routes (activities/uploads have no waytags).
• (B, future) Overpass map-matching — snap arbitrary route geometry to OSM ways and read surface/highway server-side. Covers imports/uploads, but it's expensive, approximate, rate-limited, and an external dependency. Parked for when we want imports covered (the repo already proxies Overpass for POIs).

v1 ships (A). Routes without the data degrade to no bars.

D2: Store a compact distance-weighted summary, not per-segment data

The bars need proportions, not geometry. At save, sum the haversine length of each coordinate segment into its surface bucket (and highway bucket), yielding { surface: { asphalt: <m>, gravel: <m>, … }, highway: { … } } (metres per category). This is tiny (a handful of keys), stored as a nullable surface_breakdown jsonb on routes. Per-segment data (for future map line colouring) is deliberately not persisted in v1 — that's a bigger payload and a separate feature.

D3: Handoff carries it

api.save-to-journal adds surfaceBreakdown to the POST body alongside gpx; the Journal callback validates (Zod, all values ≥ 0) and stores it. The field is optional, so the handoff stays backward-compatible and non-Planner callers (if any) are unaffected. Re-saving a route recomputes/overwrites it.

D4: Rendering

A SurfaceBreakdown component renders one horizontal stacked bar per dimension (surface, then waytype): segments sized by percentage, coloured via SURFACE_COLORS / HIGHWAY_COLORS (DEFAULT_* for unknown), with a legend listing each category + km + percent (largest first). Unknown/unmapped tags collapse into an "other" segment. Hidden entirely when surface_breakdown is null or empty. Labels via i18n; distances via stats.ts.

Risks / Trade-offs

• Coverage gap — only Planner routes get bars in v1. Acceptable: routes are designed in the Planner, which is exactly where "how much gravel" matters. Imports get bars later via (B).
• Tag sparsity — OSM surface is often missing; those segments bucket as unknown/"other". We show it honestly rather than guessing.
• Stale on edit — editing a route's geometry elsewhere without re-routing could leave the breakdown stale; recomputing on every Planner save keeps it fresh for the normal flow.