Zoning Tool — Current State
& Rebuild Brief

01 · Executive summary

A parcel database that works, on a rules layer that doesn’t scale

Compact Cottages’ “Zoning Search” is a three-app system — a NestJS API, an admin panel, and a public lookup site — on DigitalOcean, built by a previous Upwork development vendor, plus a separate, polished “Can I build an ADU?” tool (a Rowan-built mockup) embedded on the CC marketing website. A visitor types an address; the system finds the parcel, looks up its zoning district, and shows which of CC’s 23 housing products are allowed (Yes / No / Maybe) — and, for a sliver of districts, dimensional numbers like setbacks and max ADU size.

The parcel side works and scales: 337,812 active parcels across Buncombe, Durham, and Henderson counties (observed live 2026-08-19). The intelligence layer does not. Every allowed-use cell and every dimensional number is hand-typed into the admin, joined to parcels by an exact text string, and the math runs only in the visitor’s browser. Six months in, district-specific dimensional constants exist for exactly two Asheville districts (plus jurisdiction-level flag-lot widths and one Asheville-wide ADU-cap formula); Durham has one real formula, Henderson none.

The plan (decided Aug 19, across two calls — Rowan internal, then with Scott, Steve & Barry): Rowan builds it internally and ships the front-end first as a working sales tool on the new website (~Sept 7), publishing at ~60–70% coverage and ~90% data accuracy with plain caveats (e.g. “assuming city water & sewer”). We keep the fast DigitalOcean database; Scott perfects each county in Excel and Claude pushes his validated CSV into the DB via an API/MCP — giving Scott and Steve ownership of the data rather than a developer re-typing it. One backend powers three surfaces: the CC ADU page, a standalone tool, and an embeddable realtor widget. The Monday ask: confirm this direction.

02 · Current state

What exists today, in plain English

1. A parcel database that works. Scott Adams (CC’s land planner, AICP) hand-builds a giant spreadsheet per county — county parcel maps into ArcGIS, zoning joined onto every parcel, cleaned up in Excel, saved as CSV. Someone uploads that CSV in an admin panel; it lands in a database on DigitalOcean. Three counties are live (counts observed in the admin UI on 2026-08-19): Buncombe 134,420 · Durham 132,268 · Henderson 71,124. Address lookup over these is fast and solid.
2. A hand-typed rules layer that mostly doesn’t exist yet. Knowing a parcel’s zoning district is only half the answer — you also need “what does that district allow, and with what dimensions?” That knowledge lives in Scott’s “Zoning Translator” Excel workbook (18 jurisdictions across 4 counties, 23 CC housing products, a 0/1/2 = No/Yes/Maybe grid, plus dimensional-standards sheets). Only part of it has been re-typed into the app: the Yes/No/Maybe grid for 14 jurisdictions (~120 districts), and dimensional numbers for essentially two districts (RM8 and HB in Asheville) plus one ADU-size formula and flag-lot widths. Durham and Henderson parcels are searchable, but the tool can’t say much about what you can build there.
3. Three front-ends. (a) The “Can I build an ADU?” page on compactcottages.com — polished, cinematic (satellite fly-in to your lot), gives a verdict, fits CC models, has an AI-written plain-English summary. Buncombe-only. This is a Rowan-built mockup. (b) The raw zones-site lookup app — the previous vendor’s public front-end: search by address, PIN, or owner; see data pills. No map, no verdict, and it exposes internal taxonomy and owner names publicly. (c) A B2B / realtor plugin (the realtor lot widget) that embeds the same lookup on a partner/realtor site — also a Rowan-built mockup. All three read the same property endpoint, GET /properties/{id}.
4. Hacks holding it together. The ADU page’s instant address autocomplete is a 3.5 MB file of every Buncombe address baked into the page, regenerated by hand whenever data changes, because the live search API was too slow (5–7 s). The math (setbacks, ADU size) is computed in the visitor’s browser from formula “token trees,” not on the server.
5. Real security problems. The property/search API is public with no login, IDs are sequential, and rows contain owner names + mailing addresses — the whole owner dataset is scrapeable. Worse than a “default password”: on every restart the API resets the admin account’s password back to password123 whenever the stored hash doesn’t match it — so even an admin who dutifully changes the password is silently reverted on the next deploy. Details in Limits.

03 · Architecture

The component map

Eleven moving parts. Three DO apps and a managed Postgres form the previous vendor’s core; the consumer funnels (the ADU tool and the realtor widget), the external map/imagery, the AI copy layer and the static address index are Rowan-built mockups/additions layered on top — each is flagged below. Component names link to their live page.

04 · Current flow

Address in → verdict out, step by step

The consumer path through the internal ADU tool — the flow that matters commercially. By default the delivered app makes exactly one call (the parcel + rules fetch); the lot geometry, satellite fly-in and AI prose are Rowan additions in the mockup to make the result more UI-friendly. The verdict never leaves the browser. In the swimlane and the six stages below, 0–2 are the existing tool and 3–6 are Rowan’s additions.

05 · Rule systems

Three artifacts hold the zoning knowledge — none of them sync

The Zoning Translator workbook is the spec; the app’s two rule systems are partial manual re-keyings of it that have already drifted apart. All three join to parcels through one exact text string, zoning_district_location (e.g. “RM8 Asheville”, “R-2 Buncombe County”).

The reconciliation, made crisp

• The Translator is the spec. 2026_08_11_Zoning_Translator.xlsx, 39 sheets: a master Uses matrix of 219 rows × 23 uses (0/1/2; “2 = Maybe” means discretionary review) spanning 18 jurisdictions across 4 counties, plus 18 per-jurisdiction Dimensional sheets holding the authoritative numbers, and a plain-English ADU rule summary. Nothing in the app reads it directly.
• The Matrix (System 2) = the Translator’s Uses sheet, re-typed for 14 of 18 jurisdictions (~120 district rows). Verified: the 23 columns match the workbook’s 23 uses exactly, and a live parcel returns the same 23 flattened_values. It is global and unversioned — a cell edit changes every county instantly, silently, with no audit trail — and a live DB constraint makes each district code globally unique, which is why “RS8 (Asheville)” and “RS8 (Durham)” can’t coexist without concatenating the jurisdiction into the string.
• Calculated Fields (System 1) = the Translator’s Dimensional sheets, re-typed as formulas for essentially 2 districts of 1 county: Buncombe (dataset 8) holds 15 fields — RM8 (6) + HB (5) district constants, 3 jurisdiction-level flag-lot widths, and the one genuine calculation, the Asheville-wide ADU cap min(0.70×HLA, 800). Durham: 1 real formula + 1 empty placeholder. Henderson: placeholder only. Per-dataset — re-importing a county orphans its formulas. (The round-to-10 seen in older docs is not in the stored field — it lives only in the website’s presentation layer, applied to every displayed ADU cap.)
• The conceptual seed (ZoningSearchFormulaExamples.xlsx) shows the intended design: the Uses matrix gates which dimensional fields even display — realized today via each field’s visibility expression.
• A vestigial third system exists in documentation only. The admin Home screen still documents an “Upload Zoning Rules CSV” step with a flat column contract (min_lot_size_sqft, adu_allowed, …) — but those exact columns were dropped by the matrix-refactor migration. The help text is stale; treat bulk rules import as absent (confirm with Scott).
• The scoping mismatch is a live trap: global/unversioned matrix vs per-dataset formulas. Edit a cell → every county changes silently; re-import a county → re-author every formula.

06 · Coverage & data reality

What actually works, county by county

This grid resolves the older “Buncombe only” and “5 markets” claims — prefer it. Three counties are loaded and searchable; buildability output exists almost nowhere yet. Launch markets: Asheville, Buncombe, Durham (the active-selling markets); other counties follow.

Where the data comes from — the three datasets

Every answer the tool gives is assembled from three data sets, plus live geometry and AI text:

Plus: lot geometry & dimensions come live from ArcGIS (not stored); building size / heated area is appended from public real-estate files; the satellite fly-in is a separate imagery API; and Claude writes the plain-English summary around the numbers.

How the data gets made — Scott’s 3 stages, per county manual

Stage 1 · ArcGIS Pro: spatial/tabular joins of zoning polygons and tables onto parcels; hand-minted special districts (Asheville “RS2 7F”-style codes from the sevenf flag, Durham “RS-8/RS-10 UrbanTier,” Chapel Hill CD tags). Stage 2 · Excel: rename / concat / derive — Zoning District Location = District & " " & Location: the join key is literally an Excel concatenation; PIN manually renamed to Pin every time. Stage 3: save-as CSV → admin upload → Activate. Buncombe’s production CSV: 105 columns, 134,868 rows. The API keeps the whole raw row in JSONB metafield and promotes 12 mapped columns.

Known quirks that must survive into the rebuild

• Heated-living-area semantics differ per county — Buncombe/Henderson raw SqFeet includes garage (needs the separate finished-area table); Durham’s is already house-only.
• Free text inside numeric cells — “35 (20 steep slope)”, “min 24, max 265”, “10, per State septic rules”; overlays (Steep Slope, Pedestrian Area, 7F, UrbanTier, Conservation District) are encoded as string annotations.
• Durham split-zoned parcels (2–3 districts on one parcel) have no answer in the single-exact-match model.
• Known upstream errors — Asheville sevenf Y/N flips; Flat Rock’s CITY split across 3 fire districts, patched in Excel.
• Durham has no Year Built (the county charges for CAMA data); and a YearBuilt header mismatch silently nulls year_built on live parcels.

Regrid — the scaling lever external

CC already holds samples of (a) Regrid’s structured zoning-rules tables (26 columns: permitted uses as-of-right/conditional + dimensional standards; sentinel values -5555/-9999 mean “no data” and must be nulled on ingest; no Orange file) and (b) Regrid’s national parcel product (187–215 columns per county: zoning join key, buildings, valuation, owners, lat/lon, FEMA flood, opportunity zones; STANDARD = 124 vs PREMIUM = 165 DBF fields — PREMIUM adds utility-availability and topography flags that map directly onto CC’s sewer/water-dependent min-lot-size permutations). Strategic read: Regrid can replace Stage 1 and most of Stage 2 for any US county and provide a first-draft rules layer to validate against; it does not capture CC’s 23-use / 0-1-2 discretionary nuance — the Translator remains the value-add layer on top.

07 · Limits

Why it doesn’t scale — exhaustive and evidenced

Rules authoring manual

• N×M hand-authored formulas (above) — the structural wall.
• Keystroke-per-cell matrix editing; no paste, no bulk fill; the documented “Upload Zoning Rules CSV” refers to a schema dropped by migration.
• Two rule systems with mismatched scoping — global/unversioned matrix vs per-dataset formulas; re-importing a county orphans its formulas; a matrix edit silently changes all counties with no audit trail.
• Three drifting copies of the same knowledge (Translator workbook → matrix → formulas), synced only by human re-typing.

The join

• Exact-string join everywhere (code == zoning_district_location; every formula guard). The key is an Excel concatenation; any casing/spacing/suffix drift = silent no-match (observed: "RM8  Asheville" double-space; a leading-space sheet name). No validation that a parcel’s district has a rule row.
• Zone-name collision across jurisdictions — Asheville RS/RM vs Buncombe R-#/OU; the same code means different things per county, the concatenated string is the only disambiguator, and the DB enforces this shape via the globally-unique code constraint. Exactly Barry’s RS2-vs-R1/R2 problem, observed live.
• Overlays as text, not data (7F, Steep Slope, Pedestrian Area, UrbanTier); split-zoned parcels unsupported.

Computation

• No server-side evaluator; three client evaluators. Numbers are computed in the visitor’s browser via new Function(...); the ADU tool (vanilla JS), zones-site (visibilityRules.ts), and the admin preview (mathjs) independently re-implement the token-tree semantics — guaranteed drift, untestable centrally.
• Numeric parcel data stored as text (acreage, parcel_sf, heated_living_area) — ad-hoc client coercion, no units.

Ingestion, ops & latency

• mode (Replace/Enlarge) captured but never read — every upload inserts; no true replace. No dedup of any kind — no intra-file, no cross-dataset, no unique constraint on parcels.pin; re-import duplicates every parcel. Multiple datasets can be active at once and search unions them.
• In-memory job queue (custom EventEmitter, not BullMQ/Redis): jobs lost on restart, single-instance only; no upload size limit.
• Manual refresh choreography: re-upload requires activate + regenerate buncombe-addresses.json + bump the DATASET label — nothing automated. Live evidence: the Jul-20 Buncombe refresh sits archived while the public label still says Feb 12 2026.
• Single admin user; no roles enforcement (see Security).
• Coverage: two of three loaded counties have no usable buildability output; Orange not loaded; even Buncombe’s dimensional coverage is 2 districts + flag-lot widths + one ADU formula.
• Latency hacks: live /search is too slow for typeahead (5–7 s) → the 3.5 MB static offline index shipped to every visitor; zones-site still exposes the slow path. Geometry/imagery depend on Buncombe’s free ArcGIS + pinnum matching — no guaranteed equivalent in other counties.

09 · Transformation

The plan — ship it, internally recommended

After today’s two calls (Rowan internal, then with Scott, Steve & Barry), the direction is decided. Rowan builds and ships this internally rather than briefing an outside developer — the team already understands 60–70%+ of the tool, the “mockup” is really ~80% of a working product, and hiring out would burn 10+ hours just to brief and interview before any code is written. Building it in-house is faster, costs the client nothing extra, and produces the clean documentation for a clean future hand-off (to Mohsen or a dedicated dev) once it’s live and proven. Target: V1 in ~1 month, aligned to the new-website launch (~Sept 7).

The technical shape (for the build)

The rest of this section is the engineering direction behind the plan — useful for the build and a future hand-off, not required reading for the Monday decision.

The two paths through the target system

Read path (public, fast): surface (ADU page / realtor widget / chatbot / zones-site successor) → GET /verdict?address|pin|id → the API resolves the parcel (Postgres, with pg_trgm typeahead served server-side — retiring the 3.5 MB client index), resolves the district via the alias map, loads that zone’s standards + uses, evaluates server-side, and returns one JSON verdict (state, allowed uses, dimensional numbers, ADU cap, fitted CC models, geometry ref). Numbers are never computed client-side again.

Author path: the editable rules store (in the existing backend, reachable over API / MCP) → validate + version → versioned upsert into the Postgres read model.

The target data model — what fixes N×M

The onboarding workflow — adding a county

1. Scott builds the data in ArcGIS + Excel: pull the county tax-office parcel file, join zoning onto every parcel (tabular by PIN, or spatial by polygon where there’s no PIN), add the standardized fields, and prepare the dimensional standards.
2. Scott exports a clean, validated CSV per jurisdiction — using liberal assumptions (e.g. city water & sewer) for a ~90% target, with the caveats noted.
3. Claude drafts the hard parts — AI can pre-fill ~90% of the uses/standards from the county’s UDO for Scott to proofread, instead of typing every cell by hand.
4. Scott validates against the UDO and signs off — the human-in-the-loop gate.
5. Claude / the API pushes the CSV into the database (the right calculations, uses and datasets) — no manual re-entry.
6. A quick coverage check confirms every active parcel’s zoning resolves before the jurisdiction goes public.

Test-first: Scott prepares a small, simplest-possible dataset (one jurisdiction, a handful of rows) so we can trace every value end-to-end — from the CSV, through the rules and calculations, to what the front-end shows — before loading thousands of parcels.

What survives, what gets rebuilt, what goes

10 · Developer brief

The build plan — near-term

Mission: finalize and ship the existing (~80%-built) tool as an accurate sales funnel on the new website — don’t rebuild it — then open the backend so Scott & Steve own the data via Claude + an MCP/API. Keep the DO/Postgres backbone and the existing ingest; add what’s missing.

What we hand the dev

• Live systems: public site zones-app-baprh.ondigitalocean.app · API zones-api-94c4p.ondigitalocean.app (Swagger /api, /api-json) · admin zones-admin-ok6tv.ondigitalocean.app · CC staging site compact-cottages-website.mitch-bb3.workers.dev · demos: cc-adu-tool-preview.pages.dev, compact-cottages-lot-widget.pages.dev, board cc-zoning-briefing.pages.dev.
• Repos / code: github.com/Barry-Bialik-Projects (zones-api / zones-admin / zones-site); local read-only clone external-code/compact-cottages/zoning-tool/; website + ADU tool github.com/rowan-build/compact-cottages-website — key files: can-i-build-an-adu.html (1,689 lines), tools/adu-entry-autocomplete.js, tools/data/buncombe-addresses.json, functions/api/adu-copy.js, tools/cc-pricing-data.js.
• Data assets: 2026_08_11_Zoning_Translator.xlsx (the rules spec) · 2026_07_17_Data_Dictionary_and_Methodology_ZONING_SEARCH.docx (Scott’s pipeline) · 2026_07_24_metadata.xlsx (field crosswalk + counts) · county COMPOSITE CSVs (Buncombe 105-col, 134,868 rows) · Scott’s “methodology” Word doc (in the “consultant files” folder — his full ArcGIS→Excel→CSV process, the seed for the MCP) · Regrid samples (reference only — the data source is county tax files + ArcGIS, not Regrid) · archive: Asheville 28-district dimensional CSV, formula-list docx.
• Specs / mockups: BRIEF-A (ADU lead magnet), BRIEF-B (realtor widget), briefs/01-realtor-integration-brief.md; the master spec + analyses A–E behind this board.
• Key code references for reuse decisions: search.service.ts:207 (string join) · csv-processor.service.ts (ingest — note the dead duplicate-warning path) · calculated-field.entity.ts (token trees) · migrations 1767787285027 (matrix refactor) and 1767891498570 (globally-unique code — the constraint the rebuild removes) · visibilityRules.ts + ADU tool :612–1036 (the evaluators being retired) · axios-instance.ts:8 (stale base-URL default) · adu-copy.js (AI layer to keep).
• People: Scott Adams (rules/data authority, AICP) · Barry Bialik (direction/decisions) · Steve Wall · Mitch (Rowan PM) · Mohsen (previous dev — some notes spell it “Mohsin,” same person; stays on the website, not this rebuild).

11 · Decisions & open questions

Where it landed — and what’s still open for Monday

12 · Sources & confidence

How this board was produced, and how much to trust each fact

The current-state facts are synthesized from five prior analyses plus two Aug-19 primary-source captures — a live admin-UI walkthrough and live API JSON — then corrected in an adversarial verification pass. The plan & decisions (§9–11) come from two Aug-19 strategy calls: a Rowan-internal session (Mitch + Amine) and the client call with Scott, Steve & Barry. Source precedence: live captures > primary source code (read-only clones) > transcripts (intent/vision) > older derived analyses. Where sources conflicted, the conflict was named and resolved, not averaged; call transcripts are unlabeled, so who-said-what is inferred from context.

High confidence — live API JSON or code, independently re-verified

The single GET /properties/{id} endpoint shared by both front-ends · Buncombe = dataset 8 with 15 calc fields · the 23-column matrix and its exact-string join · the stored ADU formula min(0.70×HLA, 800) with presentation-only round-to-10 · no server-side evaluator · no dedup + the dead duplicate-warning path · the seedAdminUser password-revert behavior · the globally-unique code constraint · zones-site’s stale base-URL default · both anchor parcels (178 Fairfax Ave id 408223 → cap 532 exact / 530 displayed; 1717 Old Haywood Rd id 403372 → cap 0, vacant).

Observed snapshot — one-time admin-UI walkthrough, 2026-08-19

Parcel counts 134,420 / 132,268 / 71,124 (≈337,812 total) · Durham 1+1 and Henderson placeholder-only calc fields · the archived Jul-20 Buncombe upload. Not reproducible from source — re-read from the admin before quoting as current.

Inference — speaker attributions

All named speaker attributions on transcript quotes: the transcripts are unlabeled turn-by-turn dialogue; quotes are verbatim, speakers are inferred from context.

Corrections applied in this final version (condensed)

• Removed a false “two property endpoints” discrepancy — there is only GET /properties/{id}; the “/search/property/{id}” claim was a mislabel of zones-site’s frontend route.
• ADU round-to-10 restated as universal presentation rounding, not fallback-only; ADU tool file size corrected to 1,689 lines.
• Orange County made precise: 3 municipalities blank; unincorporated county has partial drafts.
• “Mockups approved” softened to “positively received, no formal sign-off”; 30-day attribution re-cited to the 2026-08-03 note; “agent cc’d” marked mockup-only; $650 re-cited to the internal transcripts that actually contain it and flagged as in-flux.
• Seed-admin failure mode strengthened (it reverts changed passwords); the dead duplicate-warning code called out.
• Counts labeled as 2026-08-19 snapshots, with the 134,868-rows-vs-134,420-parcels CSV gap noted; “2 of ~120 districts” made precise (2 district-keyed + jurisdiction flag-lot widths + the Asheville-wide ADU cap).
• The globally-unique code migration named as a constraint the rebuild must drop; Mohsen/Mohsin harmonized; speaker attributions labeled as inferred.