curb: Instructions file for Claude Code

CURB — SF street parking, block by block

Context for Claude Code. Read this before editing.

What it is

A mobile-first web app that shows San Francisco street-parking rules on an interactive map: where you can park, until when it's swept, whether it's metered, and whether it's a residential permit (RPP) zone. Lets the user set a calendar reminder before the next sweep.

Stack (intentionally minimal)

• Single static file: index.html. No build step, no framework, no bundler.
• Vanilla JS + Leaflet 1.9.4 (from cdnjs) for the map.
• Basemap: self-hosted parchment raster tiles (basemap/parchment/, SELF_BASEMAP in index.html), baked from MAP_STYLE by scripts/build-basemap.sh and served by Vercel from this repo ($0). See docs/self-host-basemap-plan.md. Google (forced off 2026-06-29, billing) and CARTO (keyless tiles now watermarked "API KEY REQUIRED") are unreachable while SELF_BASEMAP is set. Legacy path: official Google Map Tiles API when GMAPS_KEY (or window.GMAPS_KEY) is set — session-token flow in initBasemap(), viewport attribution refreshed on moveend. Falls back to keyless CARTO Voyager raster tiles when no key / on any failure. Leaflet stays the map engine either way. The Google key is a client key (referrer-restrict it) kept OUT of the public repo: local dev reads a gitignored config.js (from config.example.js); on Vercel, api/config.js emits window.GMAPS_KEY from the GMAPS_KEY env var and vercel.json rewrites /config.js → /api/config.
• Everything is client-side. Data is fetched live from DataSF (Socrata) at runtime.
• Design system: fonts Anton (display) + Hanken Grotesk (body); "transit signage" aesthetic; color tokens in :root (--green clear / --amber soon / --red now / --meter permit-blue / paper+ink). Keep this language if extending the UI.

Data sources (all DataSF Socrata, CORS-open: access-control-allow-origin: *)

DataSF moved hosts: data.sfgov.org now 301s to data.sf.gov with no CORS header (and 403s any query using $select), which silently broke every browser fetch. Always use https://data.sf.gov (2026-09-27).

1. Street sweeping — yhqp-riqs https://data.sf.gov/resource/yhqp-riqs.json Fields: cnn (segment id), corridor, limits (cross streets), blockside, cnnrightleft (L/R vs digitized direction), weekday, fromhour, tohour, week1..week5 ("1"/"0" = Nth occurrence of that weekday in the month), line (GeoJSON LineString). CURRENT data. weekday can also be 'Holiday' (824 rows, one per curb side on ~590 blocks): the side's posted holiday schedule, see the holiday model below.
2. Parking meters — 8vzz-qzz9 https://data.sf.gov/resource/8vzz-qzz9.json Fields: street_name (UPPERCASE), cap_color, on_offstreet_type, lat/long, etc. CURRENT data. Used only for a street-level count (no spatial join — see limits).
3. Parking regulations / RPP — hi6h-neyh https://data.sf.gov/resource/hi6h-neyh.json Fields: regulation, rpparea1 (permit-area letter), hrlimit, days, from_time, to_time, exceptions, shape (GeoJSON MultiLineString). STALE: this is SFMTA's 2017 set, flagged by the city as not comprehensively updated. Treat as a hint. NOTE: RPP covers BOTH curbs — rendered as ONE street-wide centerline ribbon UNDER the curb lines, with zoom-scaled weight (rppWeight(): 4px@z15 → 26px@z18 ≈ curb-to-curb). Do NOT draw offset bands per side: they stack into a blue blanket at low zoom and collide with the ±5m curb lines at high zoom (tried 2026-06-09, looked broken).
4. Loading / color-curb zones — 6cqg-dxku (Meter Operating Schedules) Field applied_color_rule carries the regulation + days_applied/from_time/to_time/ time_limit (White=passenger, Yellow=commercial, Red=truck, Green=short-term, Orange=bus). cap_color is UNRELIABLE (white zones show Grey caps) — match on applied_color_rule. No geometry → join to meter coords by post_id (8vzz-qzz9 lat/long). Metered zones only; paint-only curbs aren't published. Loaded once on toggle, rendered per-viewport.
5. Parking citations — ab4h-6ztd (23.8M rows, daily, ~2-5 day lag) STR CLEAN (TRC7.2.22) + ST CLEANIN (T37C) = street-cleaning tickets, minute-resolution. A 2024 records request (#26-5453) restored GPS lat/long on the citations: ~1.05M of ~1.35M street-cleaning tickets now match to a CNN by NEAREST CNN SEGMENT (<=40m), the primary pipeline. The old address→CNN join via EAS (3mea-di5p, keyed by stripZeros(number)|street_name) is demoted to a pre-2024 fallback for rows without GPS. Precomputed offline into data/enforcement.json — see scripts/build-enforcement-records.py and docs/sweeper-data-research.md. Powers the "🎯 Ticketed ~9:11a" lines. Feed gotchas (checked 2026-10-11 against the records file, ticket by ticket): (1) every ticket written 12:00-12:59 AM shows a WRONG hour, the first digit of the minute (00:24 → 02:24); anything that reads hours from the feed must go through fixHour (scripts/midnight-hour.mjs, used by build-stats). Reported to DataSF 2026-10-11; they replied 2026-10-15 that they are investigating. The bug never leaves a ticket at 00:01-00:59, so build-stats treats any day that has one as fixed and leaves its hours alone (logged as "feed already right on N days"): the workaround switches itself off as their fix lands. (2) The feed's latitude/longitude (added mid-2026) geocode the typed ADDRESS, not the officer's GPS: same ticket, different block ~1 in 4 times, so keep the records file for block times. (3) The feed is missing most of Nov-Dec 2024. The records file is complete (1,351,709 tickets, Jan 2024 to Jun 2026), but in two tabs: 'Report 1' stops at Excel's row limit and 'Report 1(1)' holds the other 303k (mostly Aug 2025 to Mar 2026), starting in column B with no header row. Read every tab from its first used column (until 2026-10-13 the build skipped that tab without a word, so the map used 815k matched tickets instead of 1.05M). The file lives in the gitignored private/ folder (private/TRC7.2.22_1.1.2024_06.24.2026.xlsx, 90 MB, the build's default path; never commit or serve it). On another Mac, download it again from request 26-5453 on sanfrancisco.nextrequest.com.