Engineering/Architecture

Seed, admin seed API, setup, and bootstrap

Last updated 2026-08-21

Source files

This document summarizes who calls what for reference data and world bootstrap. It supports reset-hardening work (F-002): one orchestration story in src/lib, thin CLI/API wrappers.

Layers#

Entry	Role
`runSeed` ()	US reference core: achievements, states, policies, demographics, game config, parties, metrics, baselines, legislation types (seed + admin permanent), budgets subset, indexes. Requires an injected `Db`.
Per-target seeders (`src/lib/admin/seed/*.ts`)	Granular operations used by the admin Universal Seeder and by `bootstrapGameWorld` for UK and follow-on datasets (e.g. `seedUKRegions`, `seedBudgets`, `seedSeats`).
`POST /api/admin/seed` ()	Admin-only HTTP API: validates targets, calls lib seeders only (no handler logic in the route).
`POST /api/seed` ()	Token-protected shortcut to `runSeed` only (full US core, not UK partial targets).
	CLI: `connectDb` / `closeDb` + `runSeed`. Re-exports `runSeed` for legacy imports.
	Optional auto-seed on startup: `getDb()` + `runSeed({ db })` when the Node runtime loads.
`/api/admin/setup`	Readiness checks and scoped repair seeds (separate from full bootstrap; see that route’s GET/POST).
`bootstrapGameWorld` ()	Reset/bootstrap orchestration for the selected preset: reference seed, enabled-country data, macro/world layers, game state, officials, elections, and final verification. Used by `POST /api/admin/reset` and .

Call graph (simplified)#

flowchart TD
  CLI[scripts/seed/seed.ts] --> runSeed[runSeed in runCoreSeed.ts]
  ApiSeed[POST /api/seed] --> runSeed
  Auto[instrumentation.ts] --> runSeed
  Bootstrap[bootstrapGameWorld] --> runSeed
  Bootstrap --> LibSeed[src/lib/admin/seed/* helpers]
  AdminSeed[POST /api/admin/seed] --> LibSeed
  LibSeed --> Mongo[(MongoDB)]
  runSeed --> Mongo
  Reset[POST /api/admin/reset] --> Bootstrap
  FullCLI[scripts/world/bootstrap-full.ts] --> Bootstrap

Data location note#

Canonical US DB seed tables (states, parties, legislation types, budgets, formula grants, etc.) live in src/lib/seeds/reference/. scripts/seeds/*.ts are thin re-exports so CLI scripts (scripts/seed*.ts, simulate-*.ts) can keep ./seeds/... paths without duplicating data. Application and src/lib code should import @/lib/seeds/reference/* (not scripts/).