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
README.md
+2 -2
View File
@@ -8,14 +8,14 @@ Government is already software: statutes are code, agencies are processes, elect
## What's in here today
105,746 markdown records, every one schema-validated:
105,743 markdown records, every one schema-validated:
| Entity | Count | What it is |
|---|---:|---|
| **Person** | 13,329 | Current officeholders — federal, all 50 state legislatures, and Florida down to the municipal level. Federal members carry their bioguide ID, leadership roles, and committee seats. |
| **Body** | 275 | The institutions themselves — the U.S. House, the Senate, 49 committees, 181 subcommittees, and now the **executive branch**: the 15 Cabinet departments and the 21 Executive-Schedule Level I offices, minted from the Code's own enumerations (5 U.S.C. §§ 101, 5312). |
| **Candidate** | 2,494 | Everyone running for federal office in 2026, from FEC filings. |
| **Jurisdiction** | 29,908 | Every U.S. county (3,131), all 435 congressional districts (Census demographics on 363), every state legislative district (4,927 house, 1,897 senate), and **every incorporated municipality in the country — 19,513 cities, towns, villages, and boroughs** — keyed by Census place GEOID, with officeholders attached where the mirror has them. |
| **Jurisdiction** | 29,905 | Every U.S. county (3,131), all 435 congressional districts (Census demographics on 363), every state legislative district (4,927 house, 1,897 senate), and **every incorporated municipality in the country — 19,513 cities, towns, villages, and boroughs** — keyed by Census place GEOID, with officeholders attached where the mirror has them. |
| **LegalText** | 59,740 | **The complete United States Code** — every section of all 53 titles that carry content (Title 53 is reserved), from General Provisions to Wildlife, mirrored section-by-section from the official OLRC USLM XML at release point 119-100 (current through Public Law 119-100). |
And the axes now cross: **27,804 authority edges** link 17,031 U.S. Code sections to the executive offices they empower, so the Attorney General's node lists every one of the 2,386 sections that vests authority in it. Law and power are no longer separate piles.
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: