dc-realestate-2026: Instructions file for Claude Code

Instructions for Claude in this codebase

This repo is meant to be a starter for new projects on top of DC's open property data. When someone hands you this repo and asks for a new feature, a new visualization, or a whole new project built on the same data, this file is where you start.

The mental model

This is a two-stage pipeline with a static frontend:

DC ArcGIS REST endpoints
        │
        ▼  (pipeline/pull*.py — Python stdlib, no deps)
    data/*.json  (raw + medium-sized intermediate files)
        │
        ▼  (cp into public/)
    public/*.json  (the React app reads these via fs.readFile at build time)
        │
        ▼  (Next.js App Router — server components do the file reads)
    Rendered HTML + interactive client components

Everything in data/ is regenerable. Don't treat any JSON file as authoritative — the source of truth is DC's APIs. If something looks wrong, re-run the relevant pipeline/ script.

Conventions worth knowing before you edit

1. No build step in the pipeline. All Python is stdlib only — urllib, json, re, datetime. Don't add requests or pandas. The HTTP helper in pipeline/pull.py (http_get / arcgis_query) handles GET → POST fallback when polygon payloads make URLs too long, and pagination at the ArcGIS 2,000-row default page size.

2. Leaflet maps need dynamic imports. Leaflet touches window at import time, so any component that uses react-leaflet MUST be split into two files: Foo.tsx (a thin client wrapper using next/dynamic with ssr: false) and FooImpl.tsx (the actual leaflet-using component). See components/SalesMap.tsx / components/SalesMapImpl.tsx for the pattern.

3. Use codes are strings. ITSPE's USECODE is zero-padded — "081", not 81. Always quote when filtering.

4. DC has TWO levels of property identifier:

   • Tax lots (~30,000) — physical parcels with polygons. From layer /39.
   • ITSPE / SSL (~221,000) — one row per legal property, which includes a separate row for every condo unit. When the question is "how many of X are there?", be explicit about which one you mean. Pulls in this repo dedupe to tax lots by intersecting ITSPE.SSL with the Tax Lots layer.