CommonTable food-system planner

CommonTable is an open-source computational planning laboratory for designing and testing a replacement United States food-system operating model. It begins with population and nutritional requirements, then solves for production, producer contracts, processing and storage capacity, shipments, reserves, household affordability support, imports, and domestic-first exports.

The current food system is a comparison baseline. The intended output is a proposed operating plan with human-readable explanations and machine-readable decision traces for every major recommendation.

Geographic scope and current status

The architecture covers all 50 states, Washington, D.C., and five inhabited United States territories. Carroll County is the first high-resolution reproducibility case; Maryland is the first state expansion area. These are validation areas, not the final scope.

Implemented now:

• A deterministic monthly Pyomo/HiGHS reference model for Carroll County, Frederick County, and a two-county federation.
• Production-contract, logistics, inventory, reserve, infrastructure, household-access, disruption, and explanation outputs.
• National, regional, state, and county plan envelopes with reconciliation checks.
• A 56-jurisdiction coverage ledger and ten-stage national expansion roadmap.
• Interactive national and Maryland MapLibre planning maps built from precomputed, versioned JSON and Census GeoJSON, with an optional OpenStreetMap context layer.
• Tests for domain rules, optimization, APIs, geospatial checks, schemas, provenance, and rendered accessibility basics.

Not implemented yet:

• An evidence-complete Maryland operating plan or a national county-level solution.
• Verified facility inventories, producer bids, household travel-time microdata, or comprehensive demographic diets.
• National processing, storage, transportation, import, reserve, and export optimization.
• A claim that any checked-in proxy plan is ready for procurement or policy adoption.

The checked-in numerical case is an executable feasibility fixture. Values labeled proxy or estimated are not observations. The nationwide coverage output currently reports zero operating-ready jurisdictions.

How the replacement model works

For each month, the model converts population and diet assumptions into nutrient-bounded food demand. It selects local production contracts and external sources, conserves inventory after spoilage and transport loss, respects production and storage capacities, funds modeled access and affordability gaps, and minimizes declared operating costs. Explanations connect each selected action to alternatives, evaluated constraints, tradeoffs, assumptions, and change triggers. See methodology, mathematical model, and explainability.

Install and run

Requirements: Python 3.11–3.14, uv, and Node.js 22 or later.

After cloning the repository with the URL shown by GitHub, run:

cd Common-Table
uv sync --frozen
npm ci
make solve
make test
make validate

Run the local interface with make web and open http://localhost:3000. Run the optional local API with make api; the public site does not depend on it.

Regenerate the reference results with one command:

make solve

Verify that a fresh solve still matches the checked-in reference behavior:

make regression

Build the self-contained GitHub Pages artifact:

make pages
python -m http.server --directory .pages 4173

The .pages output contains prerendered HTML, browser assets, documentation, GeoJSON, and checksummed scenario artifacts. It needs no server, database, Python process, or commercial API. Checked-in Census boundaries and planning results remain usable without a network connection; the optional OpenStreetMap context layer requires network access and can be disabled in the interface.

The public deployment is hosted by GitHub Pages at rrg314.github.io/Common-Table. The site is built entirely from this repository by GitHub Actions; no private service, proprietary application host, or hosted backend is part of its runtime.

Repository structure

• app — strict TypeScript static-site source.
• apps/api — optional local FastAPI adapter; not required by GitHub Pages.
• packages — domain, optimization, data, geospatial, scenario, and explanation boundaries.
• data/catalog — schemas, source records, ontology, and nationwide configuration.
• data/sample — small input fixtures only.
• outputs/reference — canonical small generated reference outputs and checksum manifest.
• scripts — deterministic runners, validators, onboarding, and Pages assembly.
• docs — architecture, methods, assumptions, limitations, validation, and maintainer guidance.
• .github/workflows — CI, security, and manual Pages deployment.

Generated browser copies live under ignored public/generated; npm run sync:assets creates them from outputs/reference. Do not edit generated outputs by hand.

Data provenance and assumptions

Dataset records in data/catalog/sources.json distinguish sources used by the fixture from candidate sources not yet ingested. Each record includes license, version, retrieval status, coverage, units, transformations, limitations, and quality classification. See third-party data, assumptions, and the public limitations register.

Each scenario output records model and data versions, source commit, solver settings, execution date, geographic claim, validation status, and a content checksum. outputs/reference/manifest.json checksums the complete published reference set.

Contributing

Start with CONTRIBUTING.md. Model or policy changes require a rationale, source or derivation, unit analysis, tests, a reference comparison, and a documentation update. Dataset changes require source and license evidence, retrieval and transformation details, validation checks, coverage, and limitations. Scientific claims are reviewed independently of repository maintainership authority.

Software is licensed under Apache-2.0. Dataset rights and attribution remain separate; see THIRD_PARTY_DATA.md.