TBT — Ideas & Feature Backlog (input for the Angular rewrite plan)

Purpose: this is the feature/intent input that Fable 5 (then Opus) will turn into the transition + development plan. It sits alongside org-angular-standards.md and the current code in ../current/.

Status: horizons populated by Sandy; design decisions + foundations captured with Claude. [DECISION] = resolved choice. [OPEN] = still needs a call.

0. Guiding principles (keep the plan honest)

• Simplicity first — reusable components/services, minimal boilerplate, a well-written happy medium. No gold-plating.
• Preserve the special sauce — chainage / linear-referencing routing and the deliberate off-route → radio-the-OCC hand-off (no auto-reroute) must survive the rewrite unchanged in behaviour.
• Offline-first — the app works with no connectivity (service worker + local schedule data). Don’t regress this.
• Non-distractive by design — driver-facing UI must inform, never pressure or alarm; nothing that would concern passengers.
• Follow org Angular standards (org-angular-standards.md) unless a documented reason not to.
• Design foundations for where we’re going, not just where we are — see §4.

Hard constraints (must-not-break, unless a horizon explicitly changes it)

• Offline PWA + installable
• Chainage routing + off-route hand-off behaviour
• Landscape / in-vehicle tablet target
• [~] Runs from bundled/synced GTFS data — evolving: shifts move to API (see §2 GTFS serving); core GTFS stays on-device
• [~] Static-file deployable — evolving: optional API/telemetry endpoints introduced; app still runs offline
• Fixed thresholds live in the config service, NOT user-editable in the UI: on-time panel trigger 2 km/h, interaction-lock 10 km/h, off-route 50 m.

How to write each idea (field guide)

### <short name>
- **What / Why / Priority / Touches / Must-not-break / Depends on / Notes**
- **[DECISION]** resolved choices   **[OPEN]** unresolved questions

1. Immediate (next release — small, well-understood, high-confidence)

On-time running info

• What: While navigating a shift-planned service, when the vehicle slows below the threshold (2 km/h) for ~2 seconds, the left panel opens showing on-time running: an easy-to-glance mm:ss ahead/behind schedule, over the full stop list for the route with timepoints distinctively marked (bold/other). Shows the current position in the list and where the vehicle should be if on time.
• Why / user need: let drivers see how they’re tracking for time. MUST be non-distractive (hence the <2 km/h trigger) and MUST NOT apply undue pressure — informative, not pressuring.
• Priority: should
• Touches: position pipeline (chainage), shift view-model, stop_times data, new on-time-panel component
• Must-not-break: non-distractive rule; offline; only for shift-planned services — not shown when a route is manually selected.
• [DECISION] Trigger: open on stop, after ~2 s below 2 km/h (debounce so it doesn’t flicker); dismissable by the driver; auto-collapse when moving again.
• [DECISION] “Should-be” position: computed from stop_times scheduled times vs current time.
• [DECISION] Presentation: shown as a marker / horizontal rule within the stop list — not a new map object.
• [DECISION] Colour: early/late may use colour, but gentle only — no strong connotations (no bold red, no flashing).

Audible next-stop / turn callouts

• What: spoken callouts for upcoming stop and turn directions (uses existing speechSynthesis).
• Why / user need: hands-free, eyes-on-road guidance.
• Priority: should
• Touches: routing view-model, position pipeline, settings
• [DECISION] Must be toggleable off in settings.

Audible off-route alert

• What: a subtle audio cue when the vehicle goes off-route (isOffRoute).
• Why / user need: the off-route flag is safety-critical and must be noticeable to the driver.
• Priority: should
• Touches: routing view-model (off-route state), audio
• [DECISION] Very subtle — must not alarm or concern passengers. Pairs with the existing visual off-route flag and the radio→OCC hand-off (no auto-reroute).

Interaction lock while moving

• What: limit/disable fiddly touch interactions when the vehicle is above the speed threshold (10 km/h).
• Why / user need: distraction reduction; supports the non-distractive principle.
• Priority: should
• Touches: global UI shell, config service (threshold)
• [DECISION] Threshold 10 km/h, not UI-configurable (config service).

2. Medium-term (this quarter-ish — needs some design, still concrete)

Animation smoothing

• What: GPS updates arrive ~1/sec; the presented (“broadcast”) position is decoupled from the raw fix, so we interpolate/forecast between fixes using route + speed + acceleration.
• Why / user need: much smoother experience for drivers.
• Priority: should
• Touches: position pipeline (§4), map view-model
• [DECISION] Use dead-reckoning along the route line (project heading/speed/accel onto the known shape), not generic map easing.
• Notes: run the interpolation tick off the UI thread where practical (see §4 Web Worker).

Nav pill / arrow clamping

• What: clamp the presented nav pill to the navigation line while driving (present position on the route line). Presentation only — does not change the actual/underlying position.
• Why / user need: GPS drift currently makes it look like the driver is on the wrong side of the road.
• Priority: should
• Touches: position pipeline (§4 clamp stage), map view-model
• [DECISION] Clamp only when on-route; release to true position when isOffRoute so an actual excursion is shown honestly (never hide reality during an off-route event).

Telemetry monitoring (client-side enablement only)

• What: record ‘action’ telemetry and send to the server as a beacon — usage + service-running data: start/end run, log-in/out, dwell time at each stop, menu opens, etc.
• Why / user need: understand how the app is used and how the bus service is running.
• Priority: should
• Touches: new telemetry service, most view-models (emit events), config service
• Must-not-break: offline-first; must never block or crash the driver UX.
• Scope: feature planning + all client-side code to enable it. The /telemetry backend is out of scope (§5).
• [DECISION] Transport: sendBeacon for critical/unload + fetch for batched flushes.
• [DECISION] Durability: durable IndexedDB outbox with retry/backoff (nothing lost offline).
• [DECISION] Batching: hybrid — periodic flush + immediate on key events (start/end run).
• [DECISION] Event format: JSON with a thin fixed envelope — deviceID, timestamp, eventId (UUID), eventType, schemaVersion — wrapping a flexible/ad-hoc payload per event type. Ad-hoc payload, consistent envelope so it stays parseable/dedupable/evolvable. Suggested eventTypes: auth/lifecycle, run-lifecycle, navigation, stop-dwell, UI, service-performance.
• [DECISION] Identity: every message carries deviceID + timestamp as the key identity. Driver/shift correlation is worked out separately (server-side / later), kept off the client’s critical path.
• [DECISION] Consent/privacy: implied consent — managed by org policy off-device (all vehicles are already tracked with telemetry). No in-app consent UI required.
• [DECISION] Delivery: at-least-once with per-event UUIDs (server-side dedupe).
• [DECISION] Volume: full for lifecycle events; sampling allowed for high-frequency UI events.

GTFS serving

• What: today, sign-on is a static check using ShiftID. Near term: an API call using DriverID returns the driver’s allocated activities. Core GTFS data stays on-device; only shifts.csv becomes dynamic. The config GTFS location moves out of the repo, with a configurable base_url.
• Why / user need: performance improvements.
• Priority: should
• Touches: data-manager, sign-on flow, config service, new schedule API client
• Must-not-break: offline sign-on with last-known allocation.
• [DECISION] Model behind a ScheduleSource interface — StaticFileSource now, ApiSource (DriverID → activities) later; base_url configurable; cache-then-network so sign-on works offline.

3. Long-term (directional — may need a backend, bigger bets)

Depot Mode

• What: a mode for when the vehicle returns to the depot: a very-zoomed top-down view to help drivers navigate to a specific bus spot. Very long term: a layer of polygons for specific spots; the OCC can allocate a spot (shown in a distinct colour); when stopped in a known spot, the driver is offered a confirm-spot action.
• Why / user need: help drivers find/navigate to their allocated parking spot in the depot.
• Priority: could
• Touches: map view-model, position pipeline (source), OCC push channel, spot-polygon layer
• [DECISION] Entry: via geofence polygon (depot boundary), auto-enter.
• [DECISION] Positioning: rely on the device’s default Android high-accuracy mode (WiFi-assisted) — no custom indoor positioning needed.
• [DECISION] Spot confirmation is the first OCC→driver push use case — build it as a general OCC message/allocation mechanism (see below), not a one-off.

OCC-pushed approved detour corridor

• What: rather than auto-rerouting, the OCC pushes a new sanctioned route line/corridor which the app loads and runs the chainage engine on.
• Why / user need: the natural extension of “off-route is a human decision” — the human (OCC) supplies an approved corridor; the app never invents one.
• Priority: could
• Touches: routing engine (load new shape), OCC push channel
• Must-not-break: the no-auto-reroute principle.

OCC service alerts / messages

• What: OCC → driver messages (service alerts, holds, incidents, detour notices).
• Why / user need: operational comms beyond radio; shares the push channel with depot spot-allocation and detour corridors.
• Priority: could
• Touches: new OCC message channel/service, notification UI

4. Foundational / blue-sky bets (architecture to design for now)

⭐ Position pipeline (unifies smoothing, clamping, depot, gps-test)

• Idea: one pluggable pipeline separating raw fix → filter/smooth → interpolate/forecast → clamp-to-line → broadcast position → (map, routing, telemetry).
• Why it matters now: smoothing, pill-clamping, depot positioning, and the gps-test harness are all facets of this. Model it once and each feature is a stage or a swappable source.
• Design implication: define a PositionSource interface (real GPS / interpolated / depot / synthetic-test) and ordered pipeline stages; the “broadcast” position is the single source of truth for the UI.

State management

• [DECISION] Hybrid: BehaviorSubject services for global/shared state (per org standard, maps cleanly from Knockout observables) + Angular signals for local component state. Keep it simple, low-boilerplate.

Map stays imperative

• [DECISION] Wrap MapLibre GL in a service; Angular owns the chrome/panels, not the GL canvas.

Heavy geospatial off the UI thread

• [DECISION] Run Turf over the large shapes (241k+ points) and the interpolation tick in a Web Worker to keep the UI smooth.

Config service

• [DECISION] One env-backed, remotely-overridable config for: base_url(s), API keys out of source, and fixed thresholds (2 km/h, 10 km/h, 50 m) that are not UI-editable.

Feature flags

• [DECISION] Flag features for phased rollout across the horizons above.

Golden regression tests for the chainage math

• [DECISION] Capture recorded GPS traces and assert chainage/off-route/next-stop outputs, written before the port — a provable safety net that the special sauce is preserved.

5. Explicitly out of scope

• The /telemetry backend itself (client-side enablement only is in scope).
• Custom indoor positioning for depot mode (use the device’s default high-accuracy mode).