Carolinas Regional Explorer — Application Technical Documentation

Architecture, components, and maintenance guide

Author

Kailas Venkitasubramanian

Published

October 21, 2026

Note

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

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"]

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 (the sveltekit() plugin sets the static adapter with fallback: '404.html' and runes mode); there is no separate svelte.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.

Tip

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.

Note

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 (setFeatureState per 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 with fill-pattern) over tracts whose reliability feature-state is unreliable (CV > 30%), shown only in explore mode and toggleable via setReliabilityVisible (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 the GEOAPIFY_API_KEY environment 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 under netlify 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) writes static/downloads/ (csv/<slug>.csv, data-dictionary.csv, README.txt, crxp-data.zip) from the data contract on every build, so the /data page serves them as static files (git-ignored, regenerated each build). Uses jszip (a dev/build dependency only).
  • Deploy (app): Netlify runs npm run build:full and serves build/. netlify.toml sets Cache-Control on /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.yml on push (repo Settings → Pages → Source: GitHub Actions).
  • Adapter: adapter-static with full prerender (fallback: '404.html'); the app must remain prerenderable. The only server-side code is the standalone geocoding function in netlify/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.

  1. 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 into crxp/static/data/.
  2. Run npm run build:data (or node scripts/build-data.mjs) to validate the contract.
  3. Run npm run build (which also regenerates the download artifacts), review with npm run preview, deploy.
  4. For a brand-new indicator, also add a plain-language brief to src/lib/content/indicatorBriefs.js (the indicator page falls back to the meta markdown 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 $derived over 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.mjs validation and this document.

14 Testing

  • Unit: Vitest over pure modules (series.js, spatial.js incl. 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 live static/data and a synthetic fixture in build-data.test.js.
  • Visual/e2e: manual + Playwright spot-checks during data updates (verify a refreshed indicator renders and shows the expected year/MOE).