Files

T

Fabio 6c9990a115 Docs: document the Board pipeline + Artifact redeploy step

Add `make board` and docs/board.md so the Board's rebuild-and-redeploy flow
is a documented step, not tribal knowledge. Covers why the county data is
inlined (self-contained Artifact / CSP), that build_viz.py injects it into
board.html, and that a live Artifact must be REPUBLISHED (editing the repo
file doesn't update a deployed Artifact). README links it in both the make
list and the docs index.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-07-04 21:12:05 -04:00

2.3 KiB

Raw Blame History

The Board

viz/board.html is the Board — a rebuilt view of the canonical tree, never a source. It is a nationwide county choropleth (income / population / poverty lenses) where any county opens a drill-down of its officeholders and demographics.

Pipeline

data/officeholders-v3.jsonl ─┐
data/acs_county.jsonl        ├─ scripts/build_viz.py ─> viz/board.html (inlined)
data/place_county_crosswalk  ┤                        └> viz/county_*.json (companions)
data/fec_candidates, acs_cd ─┘

build_viz.py resolves each official to a county with the same build.place_resolver + county_slug the tree uses, so the Board and the tree agree by construction. It then does two things:

Writes viz/county_data.json and viz/county_detail.json — human-readable, diffable companions.
Injects the fresh data straight into board.html, rewriting three marked lines: const D (per-county summary), const CDETAIL (per-county rosters), and const TOTALS (the header counts).

Why the data is inlined

The Board is deployed as a self-contained Artifact, and the Artifact CSP blocks every external request — no fetch, no external scripts, styles, or fonts. So the county data cannot be loaded at runtime; it must live inside board.html. That is why build_viz.py writes into the file rather than letting the page read the JSON companions (nothing reads them — they exist for diffs).

The header totals (officeholders, candidates, counties, districts) read from the injected const TOTALS object — never hardcoded — so they cannot drift out of sync on the next rebuild.

Rebuild

make board       # regenerate board.html + the JSON companions from the tree

board.html is deterministic: two runs are byte-identical.

Redeploy the Artifact

Editing board.html in the repo does not update a live Artifact — the deployed copy is a snapshot. After make board, the Board must be republished to its existing Artifact URL for the change to appear on claude.ai.

Republishing to the same URL requires passing that URL back to the publish step (Artifact url=<existing-url>); publishing without it mints a new URL. Keep the current Board Artifact URL in the team's deployment record so redeploys stay in place instead of scattering new links.

2.3 KiB Raw Blame History