radar kickoff

Radar — Claude Code Session Kickoff Plan

Companion to radar-architecture.md. This is the operating manual for building Radar with Claude Code: a paste-ready kickoff prompt, the repo map, the non-negotiable guardrails, how to verify, and a session-by-session schedule. Start a fresh Claude Code session for this — it’s a long, multi-repo build.

0. Before you start the session

Open the right working dir. This is multi-repo. Start Claude Code from the parent that contains all of them (~/rechaj/) so it can read across radar-web, hermes-java-api, vcu-consumer, rechaj-backend-api, and terraform.
Have the architecture doc in reach — Claude should read rechaj-design-system/products/hermes-web-app/docs/radar-architecture.md first thing.
Pick the model + thinking budget. Use the strongest available model with extended thinking for the spikes/ADRs (Stage 0) and gateway/protocol work (Stages 2–3); a faster model is fine for mechanical FE/layer work once patterns are set.
One stage per session (roughly). Each stage in §13 is sized to be a focused session or two. Don’t try to one-shot the whole build.

1. The kickoff prompt (paste this to start)

We are building "Radar" — a real-time God-view fleet command center for ~10k
electric tricycles in Lagos (scaling to 100k). Before doing anything, read the
architecture & build plan in full:
  rechaj-design-system/products/hermes-web-app/docs/radar-architecture.md
and this kickoff doc:
  rechaj-design-system/products/hermes-web-app/docs/radar-kickoff.md

Then confirm you understand: the two-track model (display vs truth), the
real-time data plane (WS gateway + viewport-scoped H3 subscriptions + binary
snapshot/delta + client dead-reckoning), and the hard guardrails below.

We are starting at STAGE 0 (Foundations & spike). Work strictly stage-by-stage
per §13; do not skip ahead. For this session:
  1. Scaffold the radar-web app (Stage 0.1).
  2. Build the render-ceiling spike (0.2) and prove 60fps@10k / ≥30fps@100k.
  3. Wire Carto Dark Matter + 2.5D + building extrusions (0.3).
  4. Draft ADR-001..004 stubs in docs/adr/ with the spike results.
Stop at the Stage 0 exit criteria and report; we'll review before Stage 1.

GUARDRAILS (non-negotiable — repeat them back before you start):
  - Decouple look from truth. The frontend NEVER snaps coordinates; matching is
    server-side (Valhalla), Stage 3.
  - No paid per-ping API in the hot path, ever. Self-hosted only in the live path.
  - React is OUT of the position hot loop — imperative deck.gl updates only;
    add the render-count CI guard.
  - Binary columnar on the wire (FrameCodec, Appendix A); typed arrays + workers;
    no JSON / no per-vehicle JS objects on the hot path.
  - Everything behind a feature flag; new Radar runs alongside the old app
    (strangler), never replaces it big-bang.
  - Verify every change by actually running it (perf harness / browser / load
    test), not by assertion. Show the numbers against the budgets in §4.6 / §11.

CONVENTIONS:
  - Branch + PR flow: feature branch → qa → uat → main. Conventional-commit
    titles. Use the repo's backend-* skills when touching any co.rechaj.* Java
    service (backend-new-file / backend-naming / backend-module-layout /
    backend-solid-and-patterns / backend-pr-conventions).
  - Commit/push only when I ask.

Start by reading the docs and restating the plan + guardrails for Stage 0.

2. Repo map (what gets touched, by stage)

Repo	Role	Stages	Notes
`radar-web` (new)	The app (Track A)	0,1,2-client,3-interp,5-FE,6-FE,7-FE	New Vite/React/TS repo. Reuses design-system tokens + the prototyped surfaces.
`radar-gateway` (new)	Realtime WS fan-out	2,3(Valhalla client),6	Tiny Go/Node service. Redis sub → binary WS push.
`vcu-consumer`	Telemetry ETL + match hop	2(publish),3(match),4(signals)	Add Valhalla call + Redis publish; stop dropping signals.
`hermes-java-api`	BFF / cold reads	5,6	Extend with composed endpoints + RBAC; fix single-replica scheduling before scaling.
`rechaj-backend-api`	System of record + events	5(read events),6(audit)	Read via its Redis events/inbox; don’t deep-join. Use backend-* skills.
`terraform` / EKS	Infra	2,3	Valhalla + gateway deploys; Redis; Timescale policies.
firmware (hardware team)	Signals + commands	4,6	Publish faults/temps/lock; confirm command topic. Coordinate, don’t block.

3. Guardrails, expanded (the “definition of right”)

Hot-path cost rule. If a change adds a metered vendor call per ping, it is wrong by construction. Reviewer rejects on sight.
Render budget is a gate, not a goal. Frame ≤16.6 ms with 1k visible vehicles + trails; no main-thread long task >50 ms. CI runs the headless frame-time bench + the render-count guard.
Freshness SLO. Ping→screen P95 < 3 s. The Stage-2 load harness asserts it nightly.
Backpressure is mandatory. Every new hop must degrade (coalesce/drop-to-snapshot/draw-raw), never block or freeze.
RBAC is not optional. No endpoint/field/layer ships without a role gate + an RBAC-matrix test (no field leakage).
Additive, reversible migrations only on the live Timescale hypertable; off-peak; tested on a staging copy first.
Commands ship disabled and pass a bench safety review before enable.

4. How to verify each stage (the exit gates)

Stage	Verify by
0	Perf harness shows 60fps@10k, ≥30fps@100k; screenshots of the dark basemap; ADRs merged.
1	Run the app with the mock source; eyeball smooth motion; render-count guard green; visual-regression screenshots per zoom.
2	Spin the gateway + a replayed fleet; the `k6`/WS load harness reports freshness P95 < 3 s with 200 operators over a 1-h soak; chaos test (kill Redis replica) degrades gracefully.
3	Match-rate dashboard > 95% in core clusters; off-road-jitter visual regression passes; confirm zero paid hot-path calls in traces.
4	Before/after query benchmark: full-day replay < 300 ms via caggs; compression ratio recorded.
5	Contract tests + RBAC matrix green; profile read P95 < 300 ms; every prototyped surface shows real data.
6	End-to-end immobilize on a bench VCU with an audit row + ack; offline-queue test; safety sign-off.
7	Model-eval harness reports predicted-offline precision/recall; demand pillars render; board reads real CO₂/SRRR.

General rule: mirror the design-app workflow — run it, screenshot it, read the console for errors, show the metrics. No “should work.”

5. Session-by-session schedule (suggested)

Each bullet ≈ one focused Claude Code session. Adjust to your cadence.

S0 — Foundations. Scaffold radar-web; render spike; basemap; ADR-001..004. (use extended thinking for the ADRs)
S1a — The Glow I. <RadarMap> shell + vehicle layer + binary attrs + LOD skeleton.
S1b — The Glow II. TripsLayer trails + mock live source (FrameCodec) + dead-reckoning + React boundary + render-count CI guard + selection/profile chrome.
S2a — Gateway I. radar-gateway scaffold + Redis live-state schema + vcu-consumer publish (raw) + FrameCodec encoder.
S2b — Gateway II. Subscription manager (viewport→H3) + coalescing broadcast + backpressure + presence; FE data-plane client swaps the mock; WS auth.
S2c — Load & harden. Load harness, 200-operator soak, chaos tests, metrics dashboards.
S4 — Data hardening. (can run anytime, parallel) Timescale index + caggs + compression/retention + widen schema + re-point replay.
S3a — Valhalla up. Container + tiles from OSM Nigeria + health/HPA + refresh job.
S3b — Online match. Match hop in vcu-consumer + confidence policy + matched publish + polyline interpolation on the client + fallback adapter.
S5 — BFF + RBAC. Composed endpoints + RBAC + GraphQL/batched-REST + cache + events stream; FE wires real cold reads.
S6 — Command & control. Fix command-down path + audit + guardrails + theft flag + command UI; bench E2E + safety review.
S7 — Intelligence. Demand pillars + stranding model + trace moat + extrusion polish + real board analytics + eval harness.

Parallelization: S1 (frontend) and S2/S4 (backend) are independent — run them as two tracks if you have two people / two sessions. Use subagents within a session for read-only fan-out (e.g., “scan vcu-consumer for the exact MQTT payload fields” while you scaffold).

6. First-session checklist (Stage 0, copy into the session)

Read radar-architecture.md end-to-end; restate the two-track model + guardrails.
radar-web scaffolded (Vite + React + TS), CI green (typecheck/lint/build + bundle budget).
Render spike: 10k & 100k synthetic vehicles via deck.gl binary attributes; FPS + long-task numbers captured.
Carto Dark Matter wired; 2.5D tilt + fill-extrusion buildings; screenshot.
docs/adr/001-basemap.md, 002-gateway-lang.md, 003-h3-res.md, 004-wire-format.md drafted with results.
Stop; report against the Stage 0 exit criteria; do not start Stage 1 without review.

7. Watch-outs the session should not relearn the hard way

MQTT topic namespace: firmware publishes pub/<id> but the consumer subscribes vcu/pub/#. Confirm the broker rewrite before wiring publish or commands (Stage 2/6).
hermes single-replica scheduling (no ShedLock): fix before running >1 BFF replica.
The command path is dead code (publishCommand() never connects) — treat Stage 6 as “build it,” not “call it.”
Don’t let map-matching block the demo — Stage 1 ships on the mock source; Stage 3 is independent.
Don’t put a metered API in the live path — if you’re reaching for HERE/TomTom outside fallback, stop.