phase 6: production vs published target + methodology page

Each city with a real, public housing commitment on paper now gets a
dual-line chart of cumulative units delivered vs the linear-pace
trajectory to its goal. Sources:

  NYC  Housing New York 2.0 (300k units by 2026, HPD)
  SF   Housing Element 6th Cycle (46.6k affordable by 2031, ABAG)
  LA   Housing Element 6th Cycle (184k affordable by 2029, SCAG)
  DC   Bowser Housing Framework (12k affordable by 2025, DMPED)

Targets live in lib/targets.ts with a sourceUrl and a notes field for
the messy parts (what counts as affordable here, whether the basis is
starts or completions, where our open-data sum will diverge from the
agency's own accounting).

Also adds /methodology, a long-form page documenting every datasource,
every derived metric, and the known places the math gets fuzzy. Linked
from each analytical panel. Future-me and journalists will both want
this page.

Sidebar grid goes from three toggles to four; layout flows to 2 cols.

Signed-off-by: Charlie Tonneslan <cst0520@gmail.com>

Author: c-tonneslan

README.md

@@ -14,6 +14,7 @@ Built as a portfolio piece around the question: what does it actually take to co
 - **Rent burden choropleth** — toggleable layer showing what percentage of renter households in each census tract are paying >30% of income on rent, from ACS 2022 5-year.
 - **Supply–demand gap analysis** — a PostGIS spatial join that, for every tract, counts rent-burdened households against affordable units within 1 km. Returns the worst-served tracts as a clickable list with sparkline bars.
 - **Production trends** — a stacked bar chart of units produced per year, broken down by income tier (Extremely Low → Middle Income → Other). Works on the five cities whose datasets include a project start or completion date; Chicago's feed has neither.
+- **Production vs published target** — for cities with a real, public housing commitment on paper (NYC's Housing New York 2.0, SF and LA's state-mandated RHNA cycles, DC's Bowser Housing Framework), a dual-line chart of cumulative units delivered vs the linear-pace trajectory to the goal. Every target links to its source. The page at `/methodology` documents how the comparison is computed.
 
 ## Stack
 
@@ -33,6 +34,7 @@ Built as a portfolio piece around the question: what does it actually take to co
 | `/api/gap?city=…&radius=1000&limit=25` | Worst-served tracts, ordered by (burdened households / nearby affordable units). |
 | `/api/stakeholders?city=…&district=…` | The elected representative for that district. |
 | `/api/trends?city=…` | Units per year, broken down by income tier and construction type. |
+| `/api/progress?city=…` | Cumulative units delivered vs the city's published housing target (where one is on file). |
 
 ## Run locally
 

app/api/progress/route.ts

@@ -0,0 +1,122 @@
+// GET /api/progress?city=nyc
+//
+// Joins each city's published housing-production target (see
+// lib/targets.ts) with the cumulative units actually delivered per
+// year in the open dataset, so the frontend can chart promise vs
+// delivery on one axis.
+//
+// "Per year" uses whichever of start_date or completion_date is set,
+// matching the trends endpoint. Most plans count financings or starts;
+// where a city's dataset only has completions, that's noted in the
+// target's `notes` field and shown to the user.
+
+import { NextResponse } from "next/server";
+import { db, hasDatabase } from "@/lib/db";
+import { targetForCity } from "@/lib/targets";
+
+export const runtime = "nodejs";
+
+interface YearRow {
+  year: number;
+  units: number;
+}
+
+export async function GET(req: Request) {
+  if (!hasDatabase()) {
+    return NextResponse.json(
+      { error: "DATABASE_URL is not configured." },
+      { status: 503 },
+    );
+  }
+
+  const url = new URL(req.url);
+  const cityId = (url.searchParams.get("city") ?? "nyc").toLowerCase();
+
+  const target = targetForCity(cityId);
+  if (!target) {
+    return NextResponse.json({
+      cityId,
+      target: null,
+      cumulative: [],
+      note: "No published housing-production target on file for this city.",
+    });
+  }
+
+  const sql = `
+    WITH dated AS (
+      SELECT
+        EXTRACT(YEAR FROM COALESCE(start_date, completion_date))::int AS year,
+        units_total
+      FROM projects
+      WHERE city_id = $1
+        AND COALESCE(start_date, completion_date) IS NOT NULL
+    )
+    SELECT year, SUM(units_total)::int AS units
+    FROM dated
+    WHERE year IS NOT NULL
+      AND year >= $2
+    GROUP BY year
+    ORDER BY year ASC;
+  `;
+
+  try {
+    const res = await db.query<YearRow>(sql, [cityId, target.baselineYear]);
+
+    // Walk every year from baseline → target so the chart has a clean,
+    // gap-free x-axis even when the dataset misses a year.
+    const byYear = new Map<number, number>();
+    for (const r of res.rows) byYear.set(r.year, r.units);
+
+    const yearly: { year: number; units: number }[] = [];
+    let runningTotal = 0;
+    const cumulative: {
+      year: number;
+      units: number;
+      cumulative: number;
+      targetCumulative: number;
+    }[] = [];
+    const yearsTotal = target.targetYear - target.baselineYear;
+    const perYearTarget = target.targetUnits / Math.max(yearsTotal, 1);
+
+    for (let y = target.baselineYear; y <= target.targetYear; y++) {
+      const u = byYear.get(y) ?? 0;
+      runningTotal += u;
+      yearly.push({ year: y, units: u });
+      cumulative.push({
+        year: y,
+        units: u,
+        cumulative: runningTotal,
+        targetCumulative: Math.round(perYearTarget * (y - target.baselineYear + 1)),
+      });
+    }
+
+    // Find the last year with actual data so the frontend can render
+    // "as of YEAR, you are at X% of target" honestly.
+    const lastDataYear =
+      res.rows.length > 0 ? res.rows[res.rows.length - 1].year : target.baselineYear;
+    const lastEntry =
+      cumulative.find((c) => c.year === lastDataYear) ??
+      cumulative[cumulative.length - 1];
+
+    return NextResponse.json({
+      cityId,
+      target,
+      cumulative,
+      yearly,
+      lastDataYear,
+      progress: {
+        delivered: lastEntry?.cumulative ?? 0,
+        expectedByNow: lastEntry?.targetCumulative ?? 0,
+        pctOfFinalTarget: lastEntry
+          ? Math.round((lastEntry.cumulative / target.targetUnits) * 1000) / 10
+          : 0,
+        pctOfExpected: lastEntry && lastEntry.targetCumulative > 0
+          ? Math.round((lastEntry.cumulative / lastEntry.targetCumulative) * 1000) / 10
+          : 0,
+      },
+    });
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : "unknown db error";
+    return NextResponse.json({ error: msg }, { status: 500 });
+  }
+}

app/layout.tsx

@@ -13,9 +13,9 @@ const jbMono = JetBrains_Mono({
 });
 
 export const metadata: Metadata = {
-  title: "groundwork — NYC affordable housing in flight",
+  title: "groundwork — affordable housing across six U.S. cities",
   description:
-    "Interactive map of every affordable housing project in New York City's HPD pipeline. Filter by borough, construction type, and unit count, and see what's actually being built in your neighborhood.",
+    "Interactive map of ~6,500 affordable-housing projects across NYC, SF, LA, DC, Chicago, and Philadelphia. Compare cities, see rent-burden by tract, find underserved neighborhoods, chart production over time, and measure each city against its own published housing target.",
 };
 
 export default function RootLayout({