Nexora · case study

Neighborhood intelligence, county-first

Engineering case study

A family picker on the surface.
A county-scale analytics engine underneath.

Nexora ranks neighborhoods in a county against a family's stated budget and priorities for real-estate agents. The picker is the interface; this page documents the data pipeline, scoring, and serving runtime behind it.

Role
architecture, schema, scoring, and test gates; implementation mainly through coding agents
Status
private product repository
Inspect
public Audit Edition
Nexora agent workspace: Fresno County choropleth map with ZIP boundaries, a client-brief panel, and an agent access gate
agent workspace · fresno county · every pixel traces to a versioned data bundle — note the lineage stamp in the footer

The system, in numbers

Current implementation, measured from the codebase

The current system uses Python 3.12 and SQLite. Its three Python dependencies are Shapely for geometry, WeasyPrint for PDF reports, and Pillow for images; the map client is vendored MapLibre GL. It requires no npm or Node build, cloud service, or external database.

Pipeline

8 stages

extract → adapt → normalize → snapshot → score → publish → bootstrap → serve, re-runnable end to end

Test cases

948

29,220 lines of tests against 25,865 lines of source — the tests outweigh the code

Data sources

6

county GIS, market, two school datasets, attendance boundaries, safety — one canonical schema

Database

67 tables

53 canonical pipeline tables; a separate 14-table runtime schema is all the web app can see, and its API can query 12 of those

Computed metrics

~50

per county scope, per month — the picker surfaces a fraction of them

Live demo scope

38 / 55 / 663

neighborhoods, ZIP areas, and market hex cells built across Fresno County

The face

What a buyer's agent sees

An agent describes the family once — budget, beds, school district, priorities. Hard constraints filter the county; soft preferences weight what's left; the result is a ranked shortlist with plain-language reasons an agent can hand to a client.

Every card carries its evidence: assigned schools with scores, safety relative to the county median, typical home price against the family's range — and honest caveats, like a neighborhood that straddles two attendance boundaries.

One click turns the shortlist into a branded share link or a print-ready PDF report.

Ranked shortlist: Fort Washington ranked #1 with fit score 74, school and safety scores, price context, and a boundary disclosure note
ranked shortlist · fit scores with reasons · boundary caveats printed on the card
Redesigned agent workspace: client brief chips, shortlist editor, live map
the workspace after the latest design pass — brief chips, shortlist editor, live client preview

The platform

Eight stages between a county website and a ranked answer

Data moves one direction through hard boundaries: source quirks die in the first two stages, scorers only ever see canonical facts, and the web runtime only ever reads frozen, versioned bundles. No stage can peek upstream.

  1. 1

    Extract raw, hashed on arrival

    Payloads pulled from county GIS services and public datasets — every file SHA-256-fingerprinted the moment it lands.

  2. 2

    Adapt quirks end here

    Each source family becomes a structured, versioned artifact. Downstream code never sees a source's file format again.

  3. 3

    Normalize one canonical schema

    Adapted records land in canonical tables; every run is stamped with the normalizer version that produced it.

  4. 4

    Snapshot geometry, frozen

    For a county and month: clipped polygons, hex-cell grids, school-attendance overlaps — computed once, then immutable.

  5. 5

    Score with confidence labels

    Market state per hex cell; schools and safety per neighborhood. Thin evidence shrinks estimates toward neutral instead of overclaiming.

  6. 6

    Publish sealed bundles

    Scored results become a self-contained, versioned bundle — manifest, payloads, map thumbnails — tracked in a publication index.

  7. 7

    Bootstrap fail-closed

    The runtime database is rebuilt from the latest bundle. A version mismatch refuses to load — there is no silent legacy fallback.

  8. 8

    Serve rank at request time

    A lightweight web runtime ranks against each family's preferences live, and renders the map UI, share links, and PDFs.

Scorers never see raw data. The runtime never sees the pipeline. Refreshing a county is one command.

Source lineage

Published values retain their source lineage

Families make six-figure decisions on this output, so every artifact records what it came from, when, under which code version, and with what fingerprint. Below, one real lineage pair: a raw county-GIS batch and the adapted artifact derived from it.

Two terminal panes comparing a raw batch manifest and its adapted manifest: acquisition timestamps, SHA-256 fingerprints, source URL, adapter version, and back-references from adapted to raw
raw manifest (left) → adapted manifest (right) · sha-256 lineage, timestamps, source url, adapter version, and a back-reference to the exact raw batch · local paths redacted
  • Fail-closed version gates. The normal scoring path rejects data normalized by an older schema version; the runtime rejects bundles with a mismatched payload version and reports the mismatch.
  • Shrinkage on thin data. Estimates shrink toward neutral in proportion to sample support (n / (n + k)); where coverage is too thin, the score is suppressed outright.
  • No fabricated commute scores. The UI collects a family's commute constraints, and the easy move was to fake the rest — zero-fill the data and ship a commute weight slider anyway. Instead the slider is withheld until real commute data lands.
  • Atomic report limits. Per-agent report quotas use a single guarded insert, covered by a two-thread test that fires simultaneous requests at the limit.
  • Tests outweigh the code. 948 cases, written fail-before / pass-after. The suite covers the pipeline, the scoring math, the HTTP surface, and the race conditions.

The schema, in the open

Schema and runtime boundaries

The table names below are generated from the current schema and grouped by layer. Their prefixes mark boundaries enforced in code: source-specific data is separated from canonical facts, snapshots, scores, and the 14-table serving runtime.

meta
13 tables
Run bookkeeping: counties, scopes, layers, and one row per normalization, snapshot, score, and publication build.
meta_analysis_scopemeta_analysis_scope_sourcemeta_citymeta_countymeta_county_reference_foundationmeta_county_source_policymeta_county_zipmeta_layermeta_normalization_runmeta_publication_buildmeta_score_buildmeta_snapshot_buildmeta_source_batch
ref
15 tables
Reference geography and entities: parcels, boundaries, roads, schools, attendance areas, ZIP areas.
ref_agent_tokenref_city_boundaryref_county_boundaryref_neighborhoodref_neighborhood_school_assignmentref_parcelref_parkref_reference_pointref_road_segmentref_schoolref_school_attendance_arearef_school_districtref_school_zoneref_zip_arearef_zoning_area
obs
8 tables
Observations as recorded: sales, listings, permits, assessments, school metrics, monthly ZIP market rows.
obs_assessment_observationobs_listing_eventobs_permit_eventobs_sale_eventobs_school_metricobs_vendor_property_observationobs_zip_market_monthobs_zip_sale_observation
snapshot
13 tables
A county-month frozen in place: clipped geometry, partitions, parcel assignments, serving context.
snapshotsnapshot_areasnapshot_area_parentsnapshot_parcel_assignmentsnapshot_parcel_centroidsnapshot_parcel_salesnapshot_partition_definitionsnapshot_reference_layersnapshot_rent_observationsnapshot_sale_observationsnapshot_serving_contextsnapshot_source_familysnapshot_zip_tightness_observation
score
4 tables
Scored outputs: market state, neighborhood quality, ZIP safety, and the explanation rows behind each score.
score_area_month_explanationscore_area_month_market_statescore_neighborhood_qualityscore_zip_safety
runtime
14 tables
The only schema the web app can reach. Rebuilt from a published bundle; nothing upstream is reachable from here.
runtime_cellruntime_cell_detailruntime_data_provenanceruntime_manifestruntime_neighborhoodruntime_neighborhood_school_assignmentruntime_parcel_centroidruntime_parcel_saleruntime_reference_layerruntime_saved_reportruntime_schoolruntime_school_attendance_arearuntime_zipruntime_zip_detail

generated from the CREATE TABLE statements in storage.py · 67 tables · 53 canonical, 14 runtime

Below the waterline

Built into the engine, not yet in the picker

The family picker deliberately surfaces a fraction of what the platform computes. The rest is implemented in the current serving runtime, one toggle or one data feed away.

served · layer off

Hex-cell market heat map

Heat, tightness, trend, and acceleration scored per hex cell across the county — an investor's layer, dark by default in the family product.

served · layer off

Parcel-level inspector

Parcel geometry with APN, address, and sale history behind a disabled map layer.

built · tested · one county run

New-county spin-up

The registry-driven path covers boundary validation, ZIP baselines, and GIS profiles without changing engine code. Fresno is the only county run end to end.

tracked · latest served

Longitudinal vintages

Monthly publications are indexed and retained. The runtime serves the latest; a time-series interface is not implemented.

Known limits

Current limits

  • Data staleness at serve time warns the operator but doesn't block serving — keeping data fresh is left to the operator.
  • Multi-county support is tested but has never run against more than one county for real.
  • Bundle versioning catches version mismatches, but a payload shape change within a version would slip through — a known gap, flagged in the repo's own docs.

Public audit surface

Inspect the reliability mechanisms

The product repository remains private. The public Nexora Audit Edition is a synthetic, executable extraction of five reliability mechanisms. I directed the extraction and adversarial review; coding agents produced most of the implementation under executable tests and release gates. Version 0.1.1 includes the tests, machine-readable claims, source map, known limitations, and correction record, but no product interface, real data, production configuration, or private history. It is released under AGPL-3.0-only.

Open Audit EditionRequest a product walkthrough →