Repository navigation
Description
Part of #2648. Read the epic first: it holds the model and the decisions.
Goal
A person sees the whole system in one picture, chooses an area on a map, starts a bake and watches it, on the laptop or on the bake VPS, with no keys to learn.
Wireframes
The owner approved two rounds of wireframes. Their sources, a clickable viewer and screenshots are in wireframes/obc-data/ at commit 239bb3b (branch claude/beautiful-sagan-5tcij7, a reference that is not for merging). To click through them:
git fetch origin claude/beautiful-sagan-5tcij7
git worktree add ../obc-wireframes 239bb3b18122f0228b125b2e5c22efa5ce2b7875
python3 -m http.server 8765 --directory ../obc-wireframes/wireframes/obc-data # open http://127.0.0.1:8765/Each screens/*.dc.html holds a screen's markup, and its script holds the scenario data. The data is a fake scenario. The text under "Every screen" below is the specification; the wireframes show the layout.
Screenshots (23)
Update prod from the laptop, fits 
Update prod from the laptop, does not fit
The same run, seen from the laptop 
How it runs
obc data uiserves the built page and a JSON API on127.0.0.1:8700. The API calls the same functions as the CLI; its shapes are the CLI's--jsonoutput. The page acts only on the machine that served it.- The bake VPS runs
obc data uias a systemd service.obc data open MACHINEopens one SSH tunnel (ssh -L 8701:localhost:8700 MACHINE) and the browser. Nothing is public; there is no login. - Runs elsewhere come from the target's
lock.jsonin R2 and are read only. - The page is a new Vite mode
datainbuilder/web(Svelte 5, MapLibre), so it reuses the map and area components. Licence: the server that serves GPL page assets sits on the GPL side; keephost/obc-dataMIT/Apache (tools/check_obc_data_licence.py).
Every screen
Header and navigation (every screen). OBC data · "This page runs on MACHINE" in that machine's colour (laptop charcoal, bake VPS purple in the wireframes) · OS, RAM, free store disk · "Runs here: …" · "Elsewhere: …" with a link when a run is in progress on another machine. Navigation: Overview, prod, local, Sources, Runs, Machine.
Overview. One flow diagram: Sources (6 cards with version and age) → Layers in two bands, "Device · baked per grid cell, then one catalog" and "Planner · baked once over the coverage" (cards for the 13 layers, with dependency arrows; planner layers join through a bus into planner/index) → Target card (name, where, coverage, serving release and age, readers, number of stale layers). A prod / local switch recolours the diagram. Card states: ✓ up to date, ● stale with the reason on the card, ◐ baking, ○ off. Clicking a layer shows its shape, version in code and in the target, the cause sentence, what it reads (its sources are outlined in the diagram), what bakes again after it, its readers, and "Update only this layer…" with the CLI command. Primary button: "Review update of TARGET".
Target prod. Coverage map with cells coloured by state (one tiled layer chosen at a time); the area with "Change area…"; layer list with switches for optional layers; releases (serving and rollback, "Roll back to ID"); Update → Review with fetch, download from prod, bake here, keep by reference, cost, readers, after, the machine check, the CLI command with --expect, and "Start on MACHINE". On the laptop, a scope choice ("everything stale" or "only device/map and what follows") shows the machine check passing or refusing.
Target local. Area tabs: Preset (buttons from data/regions/), Geofabrik area (search, tickable areas with extract sizes; clicking on the map ticks too), Draw a box (drag on the map, W/S/E/N fields, the extract it reads). Layer list with checkboxes: a ticked layer is rebuilt even when it is up to date. Update local with the plan line, cost and CLI command; no review. Serve on/off with links to the web planner, map builder, desktop app, simulator and the iPhone URL.
Run. Phases as a flow (Fetch → Bake → Verify → Upload → Router ready → Switch); progress per layer with time left; the cell map filling in for tiled layers; machine CPU, RAM and disk; log tail with its path; the CLI command; Stop… with a confirmation (finished work is kept; the target does not change). From another machine: read only, from the lock heartbeat, with obc data open MACHINE.
Failed run. Error box: what failed, the error, the Fix, what was kept; Resume… (the same update again) and "Clean the store". Phases show where it failed; prod unchanged; lock free.
Rollback. Confirm with what changes, "the router still runs the old release", "clients switch within a minute", "nothing is deleted". After it: a banner and "Go forward to ID".
Format change. Banner with the format changes (device/map 19.3 → 20.0). Readers table: reader, reads now, needs, what happens. Router not ready → the run waits at Router ready. Start needs a ticked acknowledgement.
Lock held. "MACHINE is updating prod" with phase and heartbeat; Update is locked; "Watch the run". Old heartbeat: open that machine first; otherwise "Take over the lock…" with the explanation that the old run stops before its switch.
Sources. Groups: OpenStreetMap; elevation, Wikimedia, climate and snow; basemap, land, assets and tools (folded). Columns: source, version, refresh per target, used by, state. Details: versions and which target uses each, upstream version, refresh policy per target (editable), licence, credential set on this machine, effect on targets, action, CLI command. Prepared sources: wiki (versions, which target uses which, "Prepare a new version…"), terrain-reference (country map and chips: prepared, preparing on MACHINE, not prepared; "Prepare a country…").
Prepare wiki. Inputs with dates and sizes, article languages, subjects (planet-wide); review with what it makes, cost and machine check; Start. While running: phases (Download dumps → Build index → Fetch photos → Publish to R2) and "when it finishes" says which layers become stale.
Machine. "What this machine can do" (each job ✓, ✗ with the reason, or ○ optional); tools with what needs them and the install command; credentials (set or not, never values); store size and Clean; first steps for a new person; "Check again".
Acceptance
- The owner walks F1 to F8 on the laptop and on the bake VPS through the tunnel: glance; local test with a drawn box; prod update on the VPS, close the laptop, check from the laptop; a revision change and a format change; prepare
wiki; roll back; a failed run and resume; a new laptop. - Every action shows its CLI command and works at phone width (16 px gutter, no horizontal page scroll; wide tables scroll in their box).
npm run checkandnpm testinbuilder/web; the suites of each crate you change. Report added and removed lines.
Depends on
P2 (#2650). Screens for local serve, the follower and prepared sources grow with P3, P4 and P6.




















Activity
timohueser commentedon Oct 12, 2026
P5-1a is merged in #2663. It adds the page shell only, in
builder/web; there is no Rust yet. The diff is +932 / −6 lines.databuilds the page.<Action>shows the exactobc data …command and posts the same args toPOST /api/cli.Failureshows the Fix line.CliQuerypolls with one request in flight, keeps the last good output beside the latest error, and gives up on an answer after 2 min.machine {name, colour, os, cores, memory_bytes, store_free_bytes}fromobc data --json.setup --jsononly when it opens and on Check again;setup --jsonhas no machine block. The data behind both comes from fixtures for now.P5-1b adds
obc data ui, with the server on the GPL side and its request guard. It also addssetup --json, the colours indata/machines.toml, the dev proxy and the README lines, after P2-1b merges.Generated by Claude Code
timohueser commentedon Oct 12, 2026
P5-1b is merged in #2667:
obc data ui,setup,openanddata/machines.toml. The diff is +1219 / −59 lines.host/obc-data-steps/src/ui.rs), reached through a hook fromobc_data::cli::main. It servesbuilder/web/dist/data/, which it builds at start, on 127.0.0.1:8700.POST /api/clirunsobc data --json ARGS.[]andsetupare allowed. Each later screen adds the verbs it uses.nullOrigin, atext/plainCSRF post and path traversal; the guard refused each one.obc data setup --json. It reports jobs, tools (Java 21+, Node 22+) with install hints, credentials by name and the store. It exits 0 when something is missing.data/machines.toml. It holds each machine's colour, checked for contrast with a charcoal fallback, and its ssh alias. The owner must add the bake VPS.obc data open MACHINE. It opens an ssh tunnel from 8701 to 8700 and then the browser.Generated by Claude Code
timohueser commentedon Oct 12, 2026
Progress on P5. These PRs are merged:
source refreshLeft for P5-6 (one PR):
After P5-6, the owner walks F1–F8 on the laptop and on the VPS. The findings go into a last P5 PR.
Generated by Claude Code
timohueser commentedon Oct 12, 2026
P5 code is complete. The last two PRs merged:
serve T --detach, router lines (router T --json), release details, a stop that arrives while a run starts.What is left for acceptance: the owner walks F1 to F8 on the laptop and on the bake VPS through the tunnel (
obc data open MACHINE). The VPS walk needs theobc data uiservice there. This issue stays open until the walk is done; findings from the walk go into one follow-up PR.Generated by Claude Code
timohueser commentedon Nov 4, 2026
This issue is closed because the work is done. The page merged (#2663, #2667, #2681, #2683, #2687, #2689, #2694, #2697), was reworked (#2847, #2865), and was used for the real prod deploy and publish (#2841, #2845). That use replaces the planned walk through F1–F8.
Generated by Claude Code