Influence-Tools/republic-os
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs: sync pass — match the validator + current architecture

Browse Source 
The docs drifted as the project moved fast. Fixed:
- Counts to the validator (canonical): 105,743 records, Jurisdiction 29,905
  (README had 105,746/29,908 — the exact-GEOID backfill dropped 3 city nodes
  and only the commit message was updated, not the docs).
- sources.md: officeholders-v2 → v3 (13,329); added the inputs that landed
  since — municipal GEOID backfill, place/district crosswalks, the complete
  U.S. Code corpus, the executive offices, and the authority edges.
- board.md: it described income/population/poverty only; now names the
  partisan-lean lens, zoom/pan, and the district+representative drill-down.
- data-model.md: stale '17,506 files' → 105,743.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Fabio
2026-07-06 13:02:48 -04:00
parent 3d8b65299f
commit 246d014a4e
5 changed files with 22 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/board.md
+7 -2
View File
@@ -1,8 +1,13 @@
# The Board
`viz/board.html` is the Board — a rebuilt *view* of the canonical tree, never a
source. It is a nationwide county choropleth (income / population / poverty
lenses) where any county opens a drill-down of its officeholders and demographics.
source. It is a nationwide county choropleth with four lenses — **income,
population, poverty, and partisan lean** (the head-count D/R balance of each
county's covering state + federal representatives) — that is **zoomable and
pannable** (scroll to zoom 1×–16× toward the cursor, drag to pan, double-click to
reset). Any county opens a drill-down of its officeholders, its demographics, and
the **districts + representatives** that cover it (congressional, state senate,
and state house, each with the share of the county it covers).
## Pipeline
docs/data-model.md
+2 -2
View File
@@ -48,7 +48,7 @@ The format conforms to the [Open Knowledge Format (OKF)](https://github.com/Goog
| **Person** | 13,329 | `us/people/`, `us/states/<st>/…/people/` | [person.schema.json](../schemas/person.schema.json) |
| **Body** | 275 | `us/bodies/…`, `us/executive/…` | [body.schema.json](../schemas/body.schema.json) |
| **Candidate** | 2,494 | `us/states/<st>/candidates/` | [candidate.schema.json](../schemas/candidate.schema.json) |
| **Jurisdiction** | 29,908 | county / city `index.md`, `us/states/<st>/districts/` | [jurisdiction.schema.json](../schemas/jurisdiction.schema.json) |
| **Jurisdiction** | 29,905 | county / city `index.md`, `us/states/<st>/districts/` | [jurisdiction.schema.json](../schemas/jurisdiction.schema.json) |
| **LegalText** | 11,221 | `legal/us/code/title-<nn>/…` | [legal_text.schema.json](../schemas/legal_text.schema.json) |
- **Person** — an officeholder, filed by the jurisdiction they serve. Federal members are enriched with their bioguide ID, leadership roles, and committee seats.
@@ -99,7 +99,7 @@ The build is deterministic by construction: sorted iteration, a fixed key order,
## Validation
[`scripts/validate.py`](../scripts/validate.py) checks all 17,506 files with no third-party dependencies:
[`scripts/validate.py`](../scripts/validate.py) checks all 105,743 files with no third-party dependencies:
1. **OKF conformance** — every file has frontmatter with a non-empty `type`.
2. **Schema conformance** — required fields, property types, and enums per entity type.
docs/roadmap.md
+1 -1
View File
@@ -5,7 +5,7 @@ An honest account of what exists, what's next, and what's further out. This repo
## Done
- **The substrate** — repo-canonical, OKF markdown + YAML frontmatter, JSON-Schema validated, deterministic build (byte-identical on rerun).
- **Five entity types, 105,746 files** — Person (13,329), Body (275), Candidate (2,494), Jurisdiction (29,908), LegalText (59,740).
- **Five entity types, 105,743 files** — Person (13,329), Body (275), Candidate (2,494), Jurisdiction (29,905), LegalText (59,740).
- **The federal government, structurally** — every member of Congress, the chambers, 49 committees and 181 subcommittees with their leadership, and every member's committee seats.
- **The nationwide county skeleton** — all 3,131 U.S. counties as demographic nodes, plus all 435 congressional districts (Census ACS demographics on 363).
- **The authority layer** — every state legislative district (4,927 house, 1,897 senate) linked county↔district↔legislator, nationwide.
docs/sources.md
+10 -2
View File
@@ -6,15 +6,23 @@ The pipeline is **repo-canonical**: raw source exports land in `data/*.jsonl` un
## Active sources
| Source | Feeds | Raw file | Authority |
| Source | Feeds | Raw file(s) | Authority |
|---|---|---|---|
| **Atlas / influence.tools** | Officeholders — federal, all state legislatures, FL county + municipal | `officeholders-v2.jsonl` (11,285) | Aggregator |
| **Atlas / influence.tools** | Officeholders — federal, all state legislatures, FL county + municipal | `officeholders-v3.jsonl` (13,329) | Aggregator |
| **Atlas / PostGIS** | Exact Census place GEOID per municipal officeholder | `officeholders-municipal-geoid.jsonl` (3,979) | Derived (Census places) |
| **congress-legislators** ([unitedstates project](https://github.com/unitedstates/congress-legislators)) | Bodies, leadership roles, committee memberships | `bodies.jsonl` (233), `leadership.jsonl` (28), `committee_memberships.jsonl` (3,879) | Community, authoritative |
| **FEC** (Federal Election Commission) | 2026 federal candidate filings | `fec_candidates.jsonl` (2,494) | Official |
| **Census ACS 2023** | County & congressional-district demographics | `acs_county.jsonl` (3,231), `acs_cd.jsonl` (363) | Official |
| **Census places + PostGIS** (via Atlas) | Place → county crosswalk behind the 19,513 municipal nodes | `place_county_crosswalk.jsonl` (32,041) | Official (Census) |
| **Census TIGER 2024 + PostGIS** (via Atlas) | County → congressional/state-leg district area-overlap edges | `county_district_edges.jsonl` (16,328) | Official (Census) |
| **U.S. Code** — OLRC USLM XML, release point 119-100 | The complete legal corpus: every section of all 53 populated titles | `legal/us/code/**` (59,740) | Official (Office of the Law Revision Counsel) |
| **U.S. Code, Title 5** (§§ 101, 5312) | The executive-branch node layer — 15 departments + 21 Level I offices | `executive_offices.jsonl` (21) | Derived from official statute |
| **U.S. Code** (all titles) | The authority axis — § → executive office it empowers | `section_authority_edges.jsonl` (27,804) | Extracted from official statute |
Atlas itself draws from official upstreams — House Clerk XML, Senate.gov XML, OpenStates, Census TIGER/Line geometry, and the Florida Cities partner API — and records the specific upstream in each record's `sources` block. So a Person file's provenance names not just "Atlas" but the document behind the field (e.g. `tenure: House Clerk XML 2026-06-10`).
The **legal corpus** is mirrored directly from the official OLRC USLM XML (no aggregator), pinned at release point 119-100 with per-title manifests and SHA-256 checksums. Pre-v1, the raw `.zip`/`.xml` snapshots live off-repo on the depot (only manifests + checksums are committed); the "raw-first, in-repo" discipline turns on at v1.0 — see the [README](../README.md#the-disciplines--the-v10-target). The **executive nodes and authority edges** are derived deterministically from the Code itself (Title 5's own enumerations, and named-reference extraction across every section) — the mirror mints part of its own structure from the law it holds.
## Provenance in every record
Each entity's frontmatter carries a `sources` list and a `confidence` level: