# Philadelphia — design & roadmap

Planning artifacts for porting the NYC school-outcomes platform to Philadelphia
(School District of Philadelphia + Philly's charter sector, ~300 schools total).
Same architecture as the NYC build: a TypeScript Next.js front-end backed by
Prisma/Postgres, fed by a sidecar Python analysis pipeline, audited by a
read-only Python validation harness. The methodology (peer groups, residual-z
outliers, comparability regimes, four-check verification) is **lifted from
KX's spec wholesale** — only the source layer changes.

## Contents

| File | What it is |
|---|---|
| `00_overview.md` | Why Philly, scope, ownership, in-repo vs new-repo decision. |
| `01_inventory.md` | Philadelphia data-source inventory — what's publicly downloadable. |
| `02_gap_analysis.md` | Philly source layer vs. NYC source layer, axis by axis. |
| `03_integration_plan.md` | P0–P5 capability sequence; analogue of KX's C0–C5. |
| `04_contribution_plan.md` | Branch/PR workflow for the Philly build. |
| `05_validation_spec.md` | The four-check (i)–(iv) taxonomy adapted to Philly sources. |
| `sources.yaml` | Source registry stub — same schema as `verify/sources.yaml`. |

## Conventions inherited from `docs/design/`

- **Validation taxonomy:** (i) completeness · (ii) base case (DB vs exact source) · (iii) spot check (DB vs official per-school report) · (iv) computed values. Same definitions as `verify/METHODOLOGY.md`.
- **Branch-per-capability** PRs; never commit directly to `main`.
- **Additive + feature-flagged** changes; the NYC site keeps working at every commit.
- **Python sidecar** for analysis; **read-only Python** for verification. TS for the app.

## Suggested reading order

`00_overview.md` → `01_inventory.md` → `02_gap_analysis.md` → `03_integration_plan.md` → `05_validation_spec.md` → `04_contribution_plan.md` → `sources.yaml`.

## Status

Draft. No Philadelphia code or data has been ingested yet; this folder is
planning + scaffolding only. Implementation begins after the open decisions in
`00_overview.md §3` are settled.