flowchart TB
subgraph Pipeline["crxp-data pipeline (separate repo)"]
PL["Ingest, calc, spatial, warehouse"] --> EXP["Export / handoff"]
end
EXP -->|writes| DC[("static/data — data contract<br/>manifest, values, analytics,<br/>aggregates, areas, meta, geo")]
subgraph App["crxp SvelteKit app"]
DC -->|fetch at runtime| DL["lib/data/* loaders"]
DL --> ST["lib/state/* rune stores"]
ST -->|effect| MC["lib/map/MapController.js"]
MC --> ML[("MapLibre GL map")]
ST --> UI["lib/components/* + routes/*"]
UI --> ML
end
BD["scripts/build-data.mjs"] -.validates.-> DC
App -->|adapter-static prerender| OUT["build/ static site"]
OUT --> NF["Netlify"]
Carolinas Regional Explorer — Application Technical Documentation
Architecture, components, and maintenance guide
Living document. This describes the CRXP web application (crxp/). Update it whenever the architecture, components, routes, build, or data contract change. Companion documents: Data Pipeline Technical Documentation and Methodology Guide (both in crxp-data/docs/).
1 Overview
The Carolinas Regional Explorer (CRXP) is a community-data web application for the 14-county Charlotte region (11 NC + 3 SC counties, ~752 Census tracts, 2020 vintage). It presents tract- and county-level indicators as interactive choropleth maps with uncertainty-aware trend charts, bivariate analysis, and spatial-cluster (LISA) analysis, plus researched per-indicator briefs, county profiles, shareable printable reports, and open-data downloads (CSV/JSON per indicator + a complete zip).
The app is a static site: all data is precomputed by the data pipeline (crxp-data/) into a documented JSON data contract under static/data/, and the app is prerendered to static HTML + assets. There is no runtime backend or database. The one exception is address search, which calls a single stateless serverless function to proxy a geocoder; every other feature, including the browser-side “use my location” lookup, runs without a server (see Section 10).
1.1 Tech stack
| Concern | Choice |
|---|---|
| Framework | SvelteKit with Svelte 5 runes ($state, $derived, $effect, $props) |
| Mapping | MapLibre GL JS (vector tiles + GeoJSON sources, feature-state value join) |
| Build / dev | Vite; @sveltejs/adapter-static (full prerender) |
| Search | Fuse.js (fuzzy area search) + address geocoding (typeahead and “use my location”) |
| Geocoding | Geoapify autocomplete + U.S. Census geocoder, via one Netlify function; client-side point-in-polygon for geolocation |
| Charts | Hand-rolled inline SVG (no chart library) |
| Hosting | Netlify (static site + one function) |
| Tests | Vitest (unit tests co-located as *.test.js) |
2 High-level architecture
Key principle — separation of geometry and values. GeoJSON layers carry only geoid; indicator values are joined at render time via MapLibre feature-state. This keeps geometry files small and lets the app swap indicators/years without reloading geometry.
Key principle — no god service. All imperative MapLibre calls live in one controller (MapController.js). UI state lives in small rune store slices. The /explore page composes them: state changes flow through $effect into the controller, which mutates the map.
3 Repository structure
crxp/
├─ src/
│ ├─ lib/
│ │ ├─ components/ # Svelte UI components (map, legends, panels, charts)
│ │ ├─ data/ # data-contract loaders + pure transforms
│ │ ├─ state/ # Svelte 5 rune stores (*.svelte.js)
│ │ ├─ map/ # MapController + color/bivariate/lisa helpers
│ │ ├─ analytics/ # spatial.js (z, breaks, Pearson/Spearman) — pure stats helpers
│ │ ├─ content/ # editorial content (indicatorBriefs.js — researched "why it matters")
│ │ ├─ geo/ # point-in-polygon + geo helpers
│ │ ├─ search/ # Fuse-based area index
│ │ └─ util/ # url state, markdown, formatting, pins
│ ├─ routes/ # SvelteKit pages (file-based routing)
│ └─ app.css # global tokens + styles
├─ static/
│ └─ data/ # THE DATA CONTRACT (produced by crxp-data)
├─ scripts/ # build-data.mjs (validator), build-data-zip.mjs (downloads), og/sitemap
├─ docs/ # this documentation (rendered to GitHub Pages via .github/workflows)
├─ .github/workflows/ # deploy-docs.yml (Quarto → GitHub Pages)
├─ vite.config.js (SvelteKit configured here) · netlify.toml
SvelteKit is configured inside
vite.config.js(thesveltekit()plugin sets the static adapter withfallback: '404.html'and runes mode); there is no separatesvelte.config.js.
4 The data contract (static/data/)
The app consumes a fixed set of JSON files. The pipeline is the producer; the app is the consumer. See the Data Pipeline Technical Documentation for how these are generated.
| File | Purpose | Loaded by |
|---|---|---|
manifest.json |
Single source of truth: schemaVersion, categories[] (themes, with color/order) + indicators[] (id, slug, label, description, category, format, decimals, higherIsBetter, years, geoLevels, source, vintage, metaPath, hasZ, hasLisa) |
state/manifest.svelte.js |
geo/tracts.geojson, geo/counties.geojson |
Geometry keyed by geoid only (counties are real dissolved polygons) |
MapController, county profiles |
values/<id>.json |
schemaVersion, per-indicator years, values{geoid:[…]}, moe/cv/reliability{geoid:[…]}, shared breaks, domain, per-year stats |
data/values.js |
analytics/z/<id>.json |
Per-year z-scores | data/analytics.js |
analytics/lisa/<id>.json |
Per-year LISA quadrants (FDR-corrected; computed by the pipeline) | data/analytics.js |
aggregates.json |
County + region averages per indicator/year, plus regionMoe/countyMoe (MOE of the mean) and breaks/domain |
data/aggregates.js |
areas/{tracts,counties,places}.json |
Names/labels (+ county bbox) for search + profiles |
data/areas.js, search/areaIndex.js |
meta/m<id>.md |
Per-indicator data-provenance markdown (“About the data”) | data/meta.js |
provenance.json |
Library + GDAL/PROJ versions that produced the data (build provenance) | — (reference) |
The contract is validated by scripts/build-data.mjs (npm run build:data, also a Vitest fixture test). It checks: a supported schemaVersion; each value file’s internal consistency (years deep-equal the manifest entry, value arrays match years length and contain only number|null, per-year stats with breaks/min/max/p1/p99); analytics presence + content (z/LISA years aligned, LISA quadrants in 0–4); aggregates present + year-aligned; and geoid reconciliation against the area manifest. Malformed JSON fails cleanly. The full app build runs this first.
Uncertainty in the contract. values/<id>.json carries per-tract moe/cv/reliability, and aggregates.json carries regionMoe/countyMoe — the MOE of the authoritative county estimate and the pooled region (not a tract average; see the pipeline’s county/region rollup). The app surfaces these as error bands on the tract, county, and region trend lines plus reliability badges, and an optional on-map hatch for unreliable tracts. Indicators without sampling MOE (raster/VIIRS) omit them and the UI degrades gracefully.
Editorial content (not in the contract). Plain-language, cited “why this matters” briefs for every indicator live in src/lib/content/indicatorBriefs.js (keyed by slug: why markdown + verified resources). They are maintained in the app repo, independent of the pipeline, and power the indicator pages and the explore “About this indicator” panel.
5 State management (rune stores)
Each store is a *.svelte.js module exporting a $state object plus mutator functions.
| Store | Responsibility |
|---|---|
manifest.svelte.js |
Loads manifest.json once; exposes categories + indicators; lookup by id/slug |
explorer.svelte.js |
Current indicator, year, geo level (tract/county); setters |
selection.svelte.js |
Hovered geoid, multi-select selectedIds[], legend class filter |
analysis.svelte.js |
Analysis mode (explore / bivariate / cluster) + mode params |
pins.svelte.js |
Pinned areas for comparison |
URL state (indicator, year, geo, mode, selection, pins) is serialized/restored via util/url.js so views are deep-linkable.
6 Map layer
lib/map/MapController.js is the only module that talks to MapLibre imperatively. It:
- builds the map, tract/county fill + line layers, and basemap/overlay handling;
- joins values via feature-state (
setFeatureStateper geoid) rather than re-styling per feature; - applies a step color expression built from the indicator’s shared breaks and the theme color ramp (
map/colorScale.js → themeRamp,buildStepExpression,legendClasses); - supports legend-class filtering/dimming, hover, multi-select, and boundary highlight;
- renders an uncertainty hatch layer (
<level>-hatch, a canvas-generated diagonal pattern withfill-pattern) over tracts whosereliabilityfeature-state isunreliable(CV > 30%), shown only in explore mode and toggleable viasetReliabilityVisible(Map settings → “Flag unreliable areas”, off by default); - swaps into bivariate (3×3,
map/bivariate.js) and LISA (map/lisaColors.js) styling for the analysis modes.
colorScale.js also provides formatValue(value, format, decimals) used across charts/legends (number, percent, dollar, years, etc.).
7 Components
flowchart LR EX["explore page"] --> MV[MapView] EX --> AMB[AnalysisModeBar] EX --> IB[IndicatorBrowser] EX --> YS[YearSlider] EX --> GLT[GeoLevelToggle] EX --> LG["Legend / LisaLegend / BivariateLegend"] EX --> TC[TrendChart] EX --> AS[AreaSearch] EX --> CP[ComparePanel] EX --> MS[MapSettings] EX --> BP["BivariatePanel / LisaPanel"]
| Component | Role |
|---|---|
MapView |
Hosts the map element; delegates to MapController |
AnalysisModeBar |
Always-visible switch between Explore / Bivariate / Spatial clusters |
IndicatorBrowser |
Theme accordion (collapsed by default) + search; indicators sorted alphabetically within each theme; a “Quality of Life Dimensions” sub-heading separates Character (general demographics) from the rest |
IndicatorSelect |
Reusable <select> that groups indicators into theme-colored <optgroup>s (alphabetical within); used by the bivariate and LISA panels |
YearSlider |
Scrubs the active year (per-indicator years) |
GeoLevelToggle |
Tract vs county view |
Legend / LisaLegend / BivariateLegend |
Class legends; hoverable filtering (incl. bivariate cell → tract filter) |
TrendChart |
Tract vs county vs region SVG trend; MOE error bands on all three lines (tract MOE; county/region from aggregates countyMoe/regionMoe), ±MOE readout, reliability badge; lines labeled County / Region (authoritative county estimate / pooled region). The band note is source-aware: ACS indicators get the rolling-5-year/non-overlapping caption; CDC PLACES indicators (crossReleaseTrend) get a model-uncertainty caption that tells users to read levels, not year-to-year change |
Trend float (in /explore) |
For a selected tract: comparable-period change markers — Δ for the 5-yr and 10-yr non-overlapping periods each with a 90% significance flag (data/series.js → comparableChanges, periods derived from the latest year) — plus provenance badges (vintage, model-based for CDC PLACES, pre-2020 harmonized for ACS). The change markers are suppressed for CDC PLACES indicators (crossReleaseTrend), whose stitched-across-releases series is not valid for trend analysis. The x-axis is year-proportional so uneven cadence renders truthfully |
BivariateScatter |
z-score scatter with marginal distributions, regression line, Pearson + Spearman (descriptive), two-way map↔︎dot hover + neighborhood name |
AreaSearch |
Fuse-based search across tracts/counties/places |
ComparePanel / PinButton |
Pin/compare areas |
MapSettings |
Basemap choice, transparency, reliability-hatch toggle |
CountyLocator |
Inset/locator map drawing the 14 real county polygons, active one highlighted, each a link (doubles as a switcher) |
CountySwitcher |
Prev/next + jump-to dropdown across the 14 county profiles |
MetricInfoPanel / MarkdownBlock |
Render an indicator’s brief; compact (sidebar) shows the lead paragraph + a “Full details & sources” link, full (indicator page) adds cited resources + “About the data” |
ProfileHero, MetricCardGrid, PercentileStrip, Sparkline, DumbbellChart |
County/city profile + report visuals. MetricCardGrid shows each card’s value, level sparkline, and a “since YYYY” change delta — the delta is omitted for CDC PLACES (crossReleaseTrend); the level sparkline is retained |
AttributionFooter |
Standard “Carolinas Regional Explorer · UNC Charlotte Urban Institute · (year)” footer on shareable/printable artifacts (profiles, reports) |
Seo, ShareButtons |
Metadata + social sharing (profiles and custom reports) |
8 Analysis modes
- Explore — single-indicator choropleth with shared cross-year breaks (so color = value is stable across years), legend filtering, hover/selection, trend chart.
- Bivariate — two indicators on a 3×3 tercile grid (rank terciles of raw values); hovering a grid cell filters matching tracts. The side panel shows a correlation scatter (
BivariateScatter): standardized (z-score) values of the two indicators, dots colored by their 3×3 class, marginal distributions, a regression line, and both Pearson and Spearman correlations labeled descriptive only (spatial autocorrelation precludes a naïve significance reading). Hovering a dot highlights the tract on the map (MapController.setHoverId) and vice-versa, and shows that tract’s neighborhood name above the scatter. - Spatial clusters (LISA) — local Moran’s I quadrants (High-High, Low-Low, High-Low, Low-High, not significant) from
analytics/lisa/<id>.json, computed once in the pipeline with a without-replacement conditional-permutation null (9,999 permutations) on rank-based normal scores, and Benjamini–Hochberg FDR.
LISA and z-scores are precomputed by the pipeline and consumed as-is (the app has no client-side LISA implementation, which avoids a second statistical code path drifting from the source of truth). lib/analytics/spatial.js keeps only the pure helpers the app still needs at runtime: z-scores, quantile breaks (for bivariate terciles), and Pearson/Spearman for the scatter.
9 Routing & pages
File-based routes under src/routes/:
| Route | Description | Prerender |
|---|---|---|
/ |
Landing page | yes |
/explore |
Main map explorer (deep-linkable via query state); sidebar “About this indicator” shows the brief lead + a link to the full page | yes |
/indicators, /indicators/[slug] |
Indicator catalog (alphabetical within theme, Character/QoL split) + per-indicator pages — “Why this matters” brief, cited “Learn more” resources, “About the data” | yes (one per indicator) |
/county/[fips] |
County profiles — real-polygon inset/locator map, 14-county switcher, metric cards, share buttons + attribution footer; OG cards | yes (one per county) |
/report |
Custom multi-tract printable report — social share buttons + attribution footer; selection encoded in the URL (?tracts=…&geo=…). Each row’s Selected value and Change are labelled with that indicator’s own years (coverage differs by source); CDC PLACES rows show “—” for change (not comparable across model releases) |
yes |
/data |
Downloads page — collapsible dimensions revealing a per-indicator data dictionary with CSV + JSON downloads, plus “Download all (.zip)” (a prebuilt static archive) | yes |
/methods, /about |
Reference pages (Methods explains MOE/reliability, rolling 5-yr, FDR-LISA, authoritative county / pooled region) | yes |
All pages are prerendered by adapter-static; /indicators/[slug] and /county/[fips] enumerate their entries from the manifest/areas at build time.
10 Address and location search
The explore page lets a resident find their neighborhood by typed address or by current location. Both resolve to a 2020 census tract and reuse the normal tract selection (pickArea), dropping a map marker at the point and flying to it.
- Typeahead (
AddressSearch.svelte) — as the user types (debounced, 3+ characters), the field requests region-filtered suggestions and shows a keyboard-navigable dropdown. Picking a suggestion resolves its coordinates to a tract by point-in-polygon (lib/geo/locate.js) against the loaded tract geometry, so no second geocoder call is needed. Clearing the field removes the marker. - “Find” (Enter) fallback — resolves the typed text precisely through the U.S. Census geocoder, which returns the tract GEOID directly.
- “Use my location” — browser geolocation, then the same client-side point-in-polygon. The coordinate never leaves the browser.
- Geocoding function (
netlify/functions/geocode.mjs) — a single stateless serverless function proxies two geocoders: Geoapify autocomplete (?suggest=, constrained to the 14-county bounding box) for typeahead, and the keyless U.S. Census geocoder (?address=) for the precise fallback. The Geoapify key is read from theGEOAPIFY_API_KEYenvironment variable and never reaches the browser. Addresses outside the region resolve to no tract and surface an “outside the region” message. Locally the function runs only undernetlify dev; “use my location” works in any dev mode because it is purely client-side.
11 Build, dev & deploy
npm install
npm run dev # local dev server (Vite)
npm run build:data # validate the data contract only (fast gate)
npm run build:zip # prebuild the download artifacts (per-indicator CSVs + data-dictionary + crxp-data.zip)
npm run build # build:data + build:zip + Vite build (prerender) → build/
npm run build:full # build:data + build:zip + OG cards + sitemap + Vite build (production)
npm run preview # serve the production build locally
npm test # vitest- Downloads are prebuilt:
build:zip(scripts/build-data-zip.mjs) writesstatic/downloads/(csv/<slug>.csv,data-dictionary.csv,README.txt,crxp-data.zip) from the data contract on every build, so the/datapage serves them as static files (git-ignored, regenerated each build). Usesjszip(a dev/build dependency only). - Deploy (app): Netlify runs
npm run build:fulland servesbuild/.netlify.tomlsetsCache-Controlon/data/*(~1 hour), so updated data can take up to that long to appear after a deploy. - Deploy (docs): this documentation is rendered from Quarto and published to GitHub Pages by
.github/workflows/deploy-docs.ymlon push (repo Settings → Pages → Source: GitHub Actions). - Adapter:
adapter-staticwith full prerender (fallback: '404.html'); the app must remain prerenderable. The only server-side code is the standalone geocoding function innetlify/functions/(outside the SvelteKit app), so the static contract is unaffected (see Section 10).
12 Updating the DATA shown in the app
Data is produced by the pipeline and handed off; the app itself rarely changes when indicators change.
- In
crxp-data, run the pipeline for the indicator(s) with--handoff— this writes/merges the value, analytics, meta, manifest, aggregates, and provenance.json files intocrxp/static/data/. - Run
npm run build:data(ornode scripts/build-data.mjs) to validate the contract. - Run
npm run build(which also regenerates the download artifacts), review withnpm run preview, deploy. - For a brand-new indicator, also add a plain-language brief to
src/lib/content/indicatorBriefs.js(the indicator page falls back to themetamarkdown if no brief exists yet).
Adding a brand-new indicator requires no app code change — the manifest entry written by the pipeline makes it appear in the relevant theme automatically (themes are fixed in the manifest categories). See the Data Pipeline Technical Documentation → “Add a new indicator”.
13 Conventions for maintainers
- Svelte 5 runes throughout; prefer
$derivedover manual effects; keep effects in the page that composes stores, not deep in components. - One controller for the map (
MapController.js); components never call MapLibre directly. - Geometry is value-free; never bake values into GeoJSON — join via feature-state.
- Pure transforms in
lib/data/*(e.g.series.js) are unit-tested; keep them side-effect free. - Match existing file size/responsibility boundaries; co-locate
*.test.js. - When you add a feature that consumes a new contract field, update
build-data.mjsvalidation and this document.
14 Testing
- Unit: Vitest over pure modules (
series.js,spatial.jsincl. z/quantile/Pearson/Spearman,colorScale.js,bivariate.js,contract.js, neighborhoods, search, url, pins, geo). - Contract:
scripts/build-data.mjs(crossCheck) is the integration gate for the data contract, exercised both against the livestatic/dataand a synthetic fixture inbuild-data.test.js. - Visual/e2e: manual + Playwright spot-checks during data updates (verify a refreshed indicator renders and shows the expected year/MOE).