Bus Theory · Maintainer Guide · Standard #1
Chapter Realignment Engine — what it is, how it was built, how to keep it alive
This page exists so the app survives its author. If Jeff Franzen is unavailable — for any reason, forever — everything needed to understand, maintain, and rebuild this tool is written here in plain English. No tribal knowledge required.
County State Identity
State abbreviations come from the county FIPS geographic prefix using the Census
state-code table. A chapter or region may cross state lines; its state label must
never override the county's geographic state. Regenerate old reports after loading
an updated app. Regression: node scripts/verify_county_state.mjs.
Move Counties Across Divisions
In a county card, choose Destination Division, Destination Region, then Receiving Chapter. Use Chapter To Be Discussed when leadership has not chosen a chapter. This changes the scenario region and division while keeping an explicit undecided chapter; it never changes the official hierarchy. Shift-click or box-select to move several counties.
The preview includes the receiving region's existing counties. Region Shapes adds that region to the displayed footprint. Saved scenarios and Undo/Redo retain undecided choices. CSV and PDF identify the regional and divisional transfer; pending chapters have no official chapter code. Choose a real receiving chapter before Auto-Balance. Change destination controls inside the county card; the top region selector starts a different scenario.
Regression check: node scripts/verify_cross_division.mjs with a loopback HTTP
server on port 8777. The check uses invented assignments and metrics, never ArcGIS credentials.
1The app in one minute
The Chapter Realignment Engine lets Red Cross leadership explore “what if” county-to-chapter boundary changes: pick a region, move counties between chapters on a map, see how population, home fires, donors, real estate, biomed, and smoke-alarm coverage would shift, auto-balance a region, and export a board-ready PDF. Nothing is ever saved back to Red Cross systems — every edit lives only in the visitor’s browser until they export it.
It is a static website: one large HTML file plus assets, no database, no server code of ours, no build step. If you can edit an HTML file and push to GitHub, you can maintain this app.
2Where everything lives
| Thing | Location |
|---|---|
| Live app (REALIGN 1) | https://realign.jbf.com — production baseline, ArcGIS sign-in for live data |
| Live app (REALIGN 2) | https://realign2.jbf.com — canonical-data pilot; same codebase, switched by hostname (or ?realign=2) |
| Source code | github.com/franzenjb/realign-realestate — branch main |
| Hosting | Vercel project realign-realestate — every push to main auto-deploys; both hostnames serve the same deployment |
| Authentication | ArcGIS Online organization sign-in controls live data access. The redundant shared-password gate was removed in September 2026. |
| Jeff’s working copy | /Users/jefffranzen/dev/realign-realestate on his Macs |
| Related data repo | ~/dev/red-cross-data — canonical county metrics mirror + FY27 hierarchy; this app reads its published outputs, never writes to it |
| Detailed change log | CLAUDE.md in the repo root, “Current state” section — dated entries for every significant change |
3How it’s built
Approved County Transitions (App-Side Overlay)
The official master geography is refreshed by NHQ GIS only twice a year, so an approved county
move can lag it by months. When leadership needs the tool to show an approved move before the
official layer does, the move goes in APPROVED_TRANSITIONS near the top of
index.html: one entry per county FIPS with the new ECODE, chapter, RCODE, region,
DCODE, and division. applyApprovedTransitions() applies it right after the hierarchy
loads and keeps the original assignment on the record, so the tooltip, the county popup, the data
note, the help modal, and the PDF source list all footnote it. This is the only place the app
departs from the official layer. Once the official layer shows the move, the overlay detects that
(same ECODE, RCODE and DCODE) and does nothing; delete the entry then. Check with
npm run verify:transitions (build and serve dist/ first; set REALIGN_TEST_URL to that server).
Jeff Franzen confirmed on September 11, 2026 that both the region and receiving chapter were officially approved. That confirmation date is not an inferred effective date. The overlay only applies to the expected source codes (13392 / 13R04 / D23); an unexpected later assignment stays unchanged and raises a review notice. No saved or imported proposal can populate this configuration. Current entries: Marion, Lewis, Clark, and Ralls counties (Missouri) from the Illinois Region to
the Missouri and Arkansas Region, ARC of Central and Northern Missouri (September 2026).
Deployment Boundary — September 2026
Vercel runs node scripts/build_site.mjs and serves dist/: the application, maintainer guide, logo, and five approved training-video sets (MP4, GIF, poster, captions). The build inserts the players into the help panel. Raw data snapshots and exported reports remain excluded. The app shell and approved training media are publicly served; live county data still requires ArcGIS sign-in.
Map Navigation
Drag to pan and scroll or pinch to zoom. The +, −, and Reset View buttons work with mouse or keyboard focus. D3 zoom transforms one geometry group containing county fills, all borders, and selection outlines. The legend and controls stay fixed. Box Select works from transformed screen bounds. Scenario recalculation preserves the view; a different geographic scope fits its counties. This changes only the on-screen view, not scenario data or report maps.
Scenario Safety And Metric Coverage
Only officially approved realignments enter baseline configuration. Every saved or imported scenario remains a proposal. Scenario files contain codes, locks and a baseline identity, but no credentials or live metric extracts. Loading an older or changed-baseline proposal requires review; importing adds a separate saved proposal and preserves open work. Existing saves remain readable and are not rewritten. Deployment does not reload active tabs.
Chapter comparisons include all counties in sending and receiving chapters. A total is unavailable when any component is missing; zero means a measured zero or an empty group. The visible coverage notice identifies incomplete measures, and Auto-Balance refuses missing weighted factors. SVI, NRI and ALICE are unweighted averages of available county scores, not population-weighted values.
Use Find in the header for a nationwide county search, or Find beside a table row. The map fits the county while retaining scenario moves and locks. County names include their geographic state.
Canonical Map Geometry
REALIGN 2 queries polygons from its existing authenticated canonical mirror, using only FIPS and geometry. TopoJSON Server 3.0.1 converts these in memory so existing borders and adjacency functions continue to work. All loaded records must have matching geometry; otherwise mapping fails visibly. No county geometry or metrics are bundled with the public site. REALIGN 1 retains its legacy-vintage public us-atlas geometry. See the repository source contract and audit regression scripts.
Architecture
index.html(~7,300 lines) is the entire application: markup, CSS, and JavaScript in one file, using the Esri ArcGIS Maps SDK for JavaScript loaded from Esri’s CDN. No framework or bundler; a small static build assembles the help media.- ArcGIS Online authenticates live data requests in the browser. The shared-password middleware was removed at Jeff’s request. Never place tokens or source-data snapshots in the static build.
story/holds a board-presentation slide deck and the official Red Cross logo asset.help/holds the training videos (below).docs/holds deep-dive runbooks.scripts/holds the tooling.
Data sources (read-only)
| Layer | What it provides | Access |
|---|---|---|
Master_ARC_Geography_2022 (FeatureServer, layer 5) | The official division → region → chapter → county hierarchy and county shapes. The service name is frozen at “2022” on purpose: NHQ GIS loads each fiscal-year vintage into the same service (sublayers are currently *_2027, item Master_ARC_Geography_FY27_July_2026), so the app picks up new geography automatically. | Public |
County_Consolidated_Metrics (FeatureServer, layer 0) | Operational metrics per county: fires, donors, real estate, biomed, smoke alarms, population | Token-gated — visitors sign in with their own Red Cross ArcGIS Online account (REALIGN 1) |
RedCross_County_Canonical_REALIGN_v1 | Canonical metrics mirror generated by the red-cross-data pipeline | REALIGN 2 reads this instead |
data.jbf.com/data/master/county_master.csv | County master CSV fallback/reference | Public |
Joins are by FIPS / ECODE / RCODE / DCODE codes — never by names. Names are labels.
4The training videos in the help modal
The help modal (? Help + data notes) opens with a five-video narrated training series recorded inside the live app on the South Florida Region. They are ordinary MP4 files with WebVTT subtitles — no video platform, no account, no cost.
- Capture:
scripts/capture_walkthroughs.mjsdrives a headless browser (Playwright) through five scripted teaching paths.scripts/capture/harness.mjsboots the app locally past the ArcGIS sign-in by serving a canned snapshot of the metrics data (the canonical mirror CSV plus a saved Florida production export infixtures/). This is why re-recording works even when Jeff’s ArcGIS token is expired. - Narration: the voice is the macOS Allison (Enhanced) text-to-speech voice, generated locally by the built-in
saycommand. Spoken lines live inscripts/capture/narration.mjs— edit that file to change what the videos say. - Assembly:
scripts/build_narrated_videos.mjspads frames so each spoken line gets picture time, mixes the audio, and emits the MP4s, posters, GIFs, and subtitle files intohelp/. - Verification:
npm run verify:help-modalchecks the modal, players, captions, and accessibility behavior end to end.
5How to maintain it — the recipes
Change wording, styling, or behavior in the app
Edit index.html in any text editor, commit, push. Vercel redeploys in about a minute. There is no build step and no dependency install for the app itself.
Change what a training video says
cd ~/dev/realign-realestate
# 1. edit the spoken lines:
$EDITOR scripts/capture/narration.mjs
# 2. serve the app locally (leave running):
python3 -m http.server 8777 --bind 127.0.0.1
# 3. re-record + rebuild (optionally pass a slug, e.g. 02, for one video):
npm run capture:walkthroughs
npm run build:videos
# 4. build and serve dist/ on another terminal:
node scripts/build_site.mjs
python3 -m http.server 8877 --bind 127.0.0.1 --directory dist
# 5. verify the built site:
REALIGN_TEST_URL=http://127.0.0.1:8877 npm run verify:help-modalCommit the changed files in help/ and push. Requires a Mac with the Allison (Enhanced) voice installed (System Settings → Accessibility → Spoken Content → Voices) and ffmpeg (brew install ffmpeg).
Record the videos in a different region or with different moves
The demo region, chapter targets, and county picks are constants at the top of scripts/capture_walkthroughs.mjs (DIVISION, REGION, county FIPS codes). Update the narration in narration.mjs to match, then re-run the recipe above.
Sign-In
Use the app’s ArcGIS Online sign-in. Access comes from existing organization permissions; there is no separate site password.
Update the underlying data
The app reads hosted ArcGIS layers; it has no data of its own. REALIGN 1 reads the live consolidated-metrics layer (updates happen upstream in ArcGIS). REALIGN 2 reads the canonical mirror, which is regenerated by the red-cross-data repo — see that repo’s runbooks. This app needs no change when data refreshes.
Deploy / rollback
Deploy = git push to main. Rollback = Vercel dashboard → Deployments → ⋯ → Promote, or git revert the bad commit and push. Every deploy keeps a preview URL, so you can test before promoting.
6Known quirks (don’t get bitten twice)
- Git push fails with HTTP 408 on slow networks (multi-MB packs of video assets). Use:
git -c core.hooksPath=/dev/null -c http.postBuffer=524288000 -c http.lowSpeedLimit=1000 -c http.lowSpeedTime=240 push. Thecore.hooksPath=/dev/nullflag is this repo’s documented git-secrets bypass. After any push oddity, confirm withgit rev-parse main origin/main— a failed push can misleadingly print “Everything up-to-date” on retry. - Escape key stops closing the help modal after a video is played and still holds keyboard focus — a Chromium limitation: the video’s media controls swallow the key before the page sees it. The × button and clicking outside always work. This is documented, tested behavior, not a bug to chase.
- ArcGIS sign-in tokens expire. If the live metrics layer stops loading, sign in again in the app. Video re-recording does not need a token (the harness serves a snapshot).
- Property spreadsheets (
*.xlsx) are gitignored on purpose. Real-estate property records must never be committed to this repo. - Desktop only. The app shows a desktop-required gate on small screens by design; don’t “fix” the modal for mobile.
7Rebuilding from zero on a new machine
- Install git, Node.js (any current LTS), Python 3, and ffmpeg.
git clone https://github.com/franzenjb/realign-realestate.gitnpm install(only needed for the video tooling — Playwright — not for the app itself).python3 -m http.server 8777 --bind 127.0.0.1and openhttp://127.0.0.1:8777— the app runs locally. Use a built dist/ server when testing the help videos.- Deploy the checked main revision to the existing Vercel project and verify both REALIGN domains in Chrome.
8Rules that protect this app
- Scenario moves never write anywhere. If a feature request implies saving back to Red Cross systems, it belongs in a governance conversation first, not in code.
- No secrets in the repo: no passwords, tokens, private ArcGIS item IDs, or property data. Live data authentication stays with ArcGIS Online.
- One logical change per commit; update
CLAUDE.md“Current state” with a dated entry for anything significant — that file plus this page are the institutional memory. - Accessibility floor: 13px minimum font, 44px touch targets, working keyboard paths. The help modal is a proper dialog (focus trap, Escape, labelled title) — keep it that way.
9About this standard
This is the first instance of Jeff’s bus-theory standard: every serious app gets a page like this one — what it is, how it was built, how to maintain it, written for a stranger — living inside the app itself, opened by two quick clicks on the Red Cross logo in the help modal. The doorway is deliberately quiet (two clicks within 700 ms, not a menu item) so end users aren’t distracted, but it is keyboard-accessible (tab to the logo, press Enter) and it is exactly what you are reading now.