Skip to content

obc data v2 · P5 — The operator page (obc data ui) #2653

Closed

Description

@timohueser

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)

Overview, prod Overview prod

Overview, local Overview local

Target prod on the bake VPS Target prod

Target prod, review open Target prod review

Update prod from the laptop, fits Update prod from laptop

Update prod from the laptop, does not fit Update prod from laptop, too big

Target local, drawn box Target local

Target local, Geofabrik area Target local area

Run on the bake VPS Run

The same run, seen from the laptop Run elsewhere

Failed run Failed run

Sources Sources

Sources, wiki selected Sources wiki

Prepare wiki Prepare wiki

Prepare wiki, running Prepare wiki running

Format change review Format change

Rollback Rollback

Rollback, confirm Rollback confirm

Rollback, done Rollback done

Machine setup Machine

prod locked by a live run Lock held

prod lock with an old heartbeat Lock stale

Take over the lock, confirm Lock takeover

How it runs

  • obc data ui serves the built page and a JSON API on 127.0.0.1:8700. The API calls the same functions as the CLI; its shapes are the CLI's --json output. The page acts only on the machine that served it.
  • The bake VPS runs obc data ui as a systemd service. obc data open MACHINE opens 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.json in R2 and are read only.
  • The page is a new Vite mode data in builder/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; keep host/obc-data MIT/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 check and npm test in builder/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

  1. timohueser commented on Oct 12, 2026

    @timohueser
    OwnerAuthor

    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.

    • Page and actions. A new Vite mode data builds the page. <Action> shows the exact obc data … command and posts the same args to POST /api/cli. Failure shows the Fix line.
    • Polling. CliQuery polls with one request in flight, keeps the last good output beside the latest error, and gives up on an answer after 2 min.
    • Header. It reads machine {name, colour, os, cores, memory_bytes, store_free_bytes} from obc data --json.
    • Machine screen. It runs setup --json only when it opens and on Check again; setup --json has 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 adds setup --json, the colours in data/machines.toml, the dev proxy and the README lines, after P2-1b merges.


    Generated by Claude Code

  2. timohueser commented on Oct 12, 2026

    @timohueser
    OwnerAuthor

    P5-1b is merged in #2667: obc data ui, setup, open and data/machines.toml. The diff is +1219 / −59 lines.

    • Server. It is an axum server on the GPL side (host/obc-data-steps/src/ui.rs), reached through a hook from obc_data::cli::main. It serves builder/web/dist/data/, which it builds at start, on 127.0.0.1:8700.
      • POST /api/cli runs obc data --json ARGS.
      • A command runs to its end and its output is read, also when the request ends first. Its standard error goes to the log of the ui.
      • Only [] and setup are allowed. Each later screen adds the verbs it uses.
    • Request guard. The Host must be a loopback name, an Origin must be loopback, and a POST must be JSON. The review probed DNS rebinding, a null Origin, a text/plain CSRF 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

  3. timohueser commented on Oct 12, 2026

    @timohueser
    OwnerAuthor

    Progress on P5. These PRs are merged:

    PR Part Lines
    #2663 and follow-ups P5-1: server, shell, Machine screen earlier
    #2681 P5-2: Runs, Run and failed-run screens +965 / −152
    #2683 P5-3: Overview flow diagram, prod and local target screens, review, resume, lock and rollback confirms +1776 / −45
    #2687 P5-4: coverage map, area picker (preset, Geofabrik, box), run cell map +656 / −44
    #2689 P5-5: Sources screen, prepared-source panels, Prepare review, detached source refresh +1001 / −125

    Left for P5-6 (one PR):

    • the local Serve card;
    • the router lines;
    • the format-change readers table;
    • the release details (age, machine, OSM version);
    • time left, CPU/RAM/disk and the log path on the run screen;
    • "Clean the store";
    • dropped leaves on the maps;
    • the GLO-30 fallback notes from P6-2.

    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

  4. timohueser commented on Oct 12, 2026

    @timohueser
    OwnerAuthor

    P5 code is complete. The last two PRs merged:

    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 the obc data ui service there. This issue stays open until the walk is done; findings from the walk go into one follow-up PR.


    Generated by Claude Code

  5. timohueser commented on Nov 4, 2026

    @timohueser
    OwnerAuthor

    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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestinfraTooling, scaffold, CI, dev harness

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions