Version 2.2.2 Devlog

[nofurtherinformation]

Release v2.2.2

Status: 🟡 In progress
Previous release: v2.2.1

Scope

A minor release with evaluation view, a report on key metrics about the demography, political, and geometric qualities of a plan. This release also includes some quality of life improvements, safety/security improvements, and miscellaneous fixes.

Tracking

• Milestone: [link]

Changelog

PR entries are appended below as they merge. See CHANGELOG.mdx for the curated public version on release.

---

[nofurtherinformation]

#527 — Centralize frontend constants

Merged: 2026-04-24 · Author: @fangge518 · Commit: ba51784
Type: ♻️ Refactor
Closes: #524

Synopsis

Consolidates string literals and union types that were duplicated across 2+ call sites into a reorganized app/src/app/constants/ tree with map/, document/, and demography/ subdirectories. Extracts tool names, column set names (TOTPOP/VAP/VOTERHISTORY), draft status, CMS rich text node/attribute names, map type/mode/route, app and map loading states, document access levels, and the demographic renderer/display mode unions. No behavior changes — this is purely a consolidation pass to eliminate stringly-typed drift and give the type system a single source of truth for these values.

Key files

• app/src/app/constants/map/ — new subdirectory; tool names, map types/modes/routes, rendering states, geography (SpatialUnit), zone layer ids, number formats
• app/src/app/constants/document/ — new subdirectory; draft status, access levels ('read' | 'edit'), temporal constants
• app/src/app/constants/demography/ — new subdirectory; column set names, demographic display mode, summary stat types (constants previously inline in utils/demography/coalition.ts)
• app/src/app/components/Cms/RichTextEditor/extensions/ — SectionHeaderNode.ts, BoilerplateNode.tsx updated to use centralized CMS constants
• app/src/app/components/RichTextRenderer/CustomRenderers/DomNodeRenderers.tsx — uses centralized node-type names
• app/src/app/components/Map/Tooltip/ — InspectorTooltip.tsx, MapTooltip.tsx updated to use new constants
• app/src/app/components/Toolbar/ToolControls/ — BrushControls.tsx, InspectorControls.tsx use ActiveTool constants
• app/src/app/store/demography/demographyStore.ts — uses centralized summary type constants
• app/src/app/utils/events/mapEvents.ts — uses centralized loading/rendering state constants
• app/src/app/components/sidebar/PopulationPanel/ — PopulationPanel.tsx, PopulationChart/PopulationChart.tsx updated for NUMBER_FORMATS

Notes

• SpatialUnit is currently typed as 'county' | 'tract' | 'block' | 'block_group' | 'voting_district'. Per @peterrrock2, special cases exist (e.g., Navajo Nation agencies) and precincts may be added case-by-case later — revisit this union when those land.

📐 ADR — Centralized constants directory with domain subfolders

Context: String literal unions ('brush', 'TOTPOP', 'default' | 'local' | 'community', 'loaded' | 'initializing' | ..., etc.) were redeclared inline at 2+ call sites across the frontend. This produced drift risk, no single source of truth, and made cross-cutting changes (e.g., adding a new map type) require grep-driven find-and-replace. Existing constants/ directory was flat and beginning to mix concerns.

Decision: Centralize all multi-use string-literal constants and their derived types in app/src/app/constants/, organized into three domain subfolders:

• map/ — maplibre / map-rendering concerns (tools, map types/modes/routes, rendering states, geography, zone layers)
• document/ — document lifecycle (draft status, access levels, temporal)
• demography/ — summary statistics display (column sets, display mode, summary types)

Alternatives considered:

• Co-locate constants with their primary consumer module. Rejected — most of these values are consumed across multiple feature modules, so any "primary" home is arbitrary and reintroduces import cycles.

Consequences:

• ✅ Single source of truth; type errors now catch typos at every call site.
• ✅ Domain subfolders give a clear home for new constants and reduce review friction ("where does this go?").
• ✅ Refactors like adding a new MapMode are now one-file changes.
• ⚠️ Imports become slightly more verbose (from '@/constants/map/tools' vs. inline literals).
• ⚠️ Some constants straddle domains (e.g., column sets touch both demography and document); the chosen home is a judgment call and may need to move.

Revisit when: A fourth domain emerges that doesn't fit map/, document/, or demography/; or when backend schemas start defining values that overlap with these unions (consider codegen at that point).

---

[fangge518]

#536 — Add evaluation metrics cache schema

Merged: 2026-04-29 · Author: @fangge518 · Commit: 9d23c52
Type: ✨ Feature
Part of: #107

Synopsis

Introduces backend scaffolding for cached plan evaluation metrics by adding a dedicated document.evaluation table and wiring it into the ORM/migration stack.

Key files

• backend/app/evaluation/models.py — adds the Evaluation SQLModel table (document_id, metrics JSONB, payload_version) with cascade FK to document.
• backend/app/alembic/versions/aa7a1c749ac0_create_evaluation_table.py — creates/drops the document.evaluation table in Alembic.
• backend/app/evaluation/registry.py — defines metric manifest structure and deterministic 63-bit payload version hashing from metric key/version pairs.
• backend/app/alembic/env.py — registers Evaluation metadata so Alembic tracks the schema.
• backend/tests/test_evaluation_registry.py — validates hash behavior for empty manifest, ordering, add/remove, and version bump cases.

Notes

• payload_version is designed for cache invalidation: any metric-set or metric-version change yields a new deterministic version.
• Future edit of metrics should upload METRICS in registry.py
• Rollback: requires migration revert (drop document.evaluation via Alembic downgrade).

📐 ADR — Store evaluation metrics as versioned JSON payload (not fixed DB columns)

Context:
We are introducing persisted evaluation metrics for documents, but the metric set is expected to evolve quickly. We also anticipate future user customization of metric options (different enabled metrics, formulas, and output shapes). A rigid schema with one DB column per metric would require frequent migrations and would optimize for querying/ranking by metric values, which is not a product goal. In fact, we want to deliberately avoid making metric-based global filtering/ranking easy by default.

Decision:
Store metrics in a JSON payload (metrics JSONB) with a payload_version stamp derived from a registry manifest, rather than creating one relational column per metric. Treat the payload as an application-level contract managed by code versioning and cache invalidation rules.

Alternatives considered:

• Fixed relational columns per metric — Rejected because every metric add/remove/shape change requires schema migration and tighter coupling between product iteration and DB evolution.
• EAV/long-form metric rows (metric_key, metric_value) — Rejected because it still encourages ad hoc ranking/filtering, increases query complexity, and does not materially improve rapid shape evolution for nested or structured metric outputs.

Consequences:
Enables fast iteration on available metrics and user-customizable metric configurations with fewer schema migrations. Supports explicit invalidation via payload_version when metric definitions change. Preserves flexibility for complex or nested metric outputs. Tradeoff: weaker direct SQL ergonomics for analytics and no first-class indexed columns for metric-based ranking/filtering (intentional product constraint). Any future need for searchable metrics should be introduced explicitly via curated derived fields/materialized views, not by widening the core table schema.

Revisit when:
Reconsider this decision if we require high-volume cross-document ranking/filtering on metric values, strict BI/reporting requirements demand stable typed columns, or performance constraints indicate payload extraction is a bottleneck.

[fangge518]

#540 — Bound API server dual-graph cache

Merged: 2026-05-06 · Author: @fangge518 · Commit: e6adccb
Type: ⚡ Perf

Synopsis

Replaces the unbounded aiocache.SimpleMemoryCache for GerryDB dual graphs with functools.lru_cache(maxsize=10),
capping per-worker memory and preventing the slow RSS climb that occurred as users touched new GerryDBs.

Key files

• backend/app/main.py — swap cache, add /_debug/cache endpoint exposing hit/miss/size + RSS
• backend/requirements.txt — add psutil for RSS reporting

Notes

• A cache miss runs synchronous S3 + disk + unpickle on the event-loop thread, briefly blocking the affected worker
  (others unaffected). Revisit if contention shows up.
• maxsize=10 is a starting value — tune from the new debug endpoint's hit ratio.
• Rollback: safe (no migrations).

[fangge518]

#538 — Add backend evaluation API with partisan metrics (and #542 bug fix)

Merged: 2026-05-13 · Author: @fangge518 · Commit: 84936a1
Type: ✨ Feature

Synopsis

Implements the backend evaluation API and all partisan redistricting metrics: seats won, efficiency gap, mean-median difference, partisan bias, Eguia score, and competitiveness. Introduces an EvaluationContext class that encapsulates per-plan vote shares and demographics as the single input to all metric functions. A new county_demographics DB table provides cached demographic aggregates, and a singleton StateIdealCache holds Eguia ideal-population values in process memory to avoid repeated DB computation.

Key files

• backend/app/evaluation/main.py — new FastAPI router exposing /evaluation endpoints
• backend/app/evaluation/partisans.py — full implementation of all partisan metrics
• backend/app/evaluation/context.py — EvaluationContext class; aggregates assignments, vote shares, and demographics using @cached_property for lazy computation
• backend/app/evaluation/models.py — updated DB models, adds CountyDemographics table model
• backend/app/alembic/versions/b4e2f8a91c30_add_county_demographics.py — migration adding the county-level demographics cache table

Notes

• The county demographics cache and StateIdealCache are keyed by GerryDB table name, not state FIPS — be careful when querying them directly.
• StateIdealCache is process-local memory; a server restart flushes Eguia ideal values and they'll recompute on next request.
• Unit tests use PYTHONHASHSEED=0 for reproducible test data generation with the help of gerrytools/gerrychain
• Rollback: requires migration revert to drop county_demographics table.

📐 ADR — In-memory singleton cache for Eguia state ideals

Context: Eguia's fairness score requires a "state ideal" — the proportional population each district should represent — which demands aggregating county-level demographics for the entire state. This query is expensive and the result changes only when underlying census data changes, not per-plan-submission.

Decision: Store computed state ideals in a process-level singleton (StateIdealCache) keyed by GerryDB table name, populated lazily on first request and retained for the server lifetime.

Alternatives considered:

• Persist in the DB alongside county_demographics. This would add another db table with little efficiency gain
• Recompute on every request — too slow; the aggregation touches all county rows for a state.

📐 ADR — Persist county demographics as a DB-cached aggregation

Context: Several metrics (Eguia, and forced county splits) require demographic data aggregated to county level. GerryDB stores data at VTD/bg/block granularity — aggregating up to county on every request means grouping thousands of rows by a substring of their path, which is expensive enough to block the API response path.

Decision: Materialize county-level aggregates into an evaluation.county_demographics table on first use, keyed by (geoid, gerrydb_table_name). Subsequent requests check for an existing row with a non-null total_pop before re-populating. The table is written once per gerrydb table and never updated.

On the key choice — gerrydb table name over state FIPS:
State FIPS was the initial candidate, but two problems ruled it out. First, most DistrictrMap
rows do not store statefps — the field exists primarily for the Navajo Nation, which spans
counties in multiple states and cannot be identified by a single FIPS code. Second, and more
practically: GerryDB table names are versioned by convention (_v1 → _v2) whenever source
geographies are updated. Using the table name as the cache key means a data refresh automatically
produces a new cache entry without any explicit invalidation — the old rows simply become orphaned
under the previous name. A FIPS-keyed cache would silently serve stale aggregates after a GerryDB
update because the key wouldn't change. The Navajo Nation multi-state edge case was noted but is
not the primary driver; evaluation metrics are not meaningful for non-political districting
projects like Navajo Nation, and a per-module evaluation toggle is planned to handle those cases
going forward.

Alternatives considered:

• State FIPS key — ruled out: most maps don't store it, doesn't survive GerryDB version bumps, and fails for multi-state regions.
• Recompute from GerryDB on every request — ruled out; the GROUP BY over thousands of VTD/block rows is too slow for a synchronous API endpoint.
• In-memory cache (analogous to StateIdealCache) — rejected because county demographics are larger (one JSONB blob per county per state) and the in-memory approach doesn't survive restarts or scale across workers.
• PostgreSQL materialized view over GerryDB — cleaner in principle, but requires tight schema coupling to the GerryDB tables and a manual REFRESH trigger; the application-level cache gives the same result with less infrastructure dependency.

Consequences: County demographics are populated lazily on the first Eguia request for a given
state, adding latency to that one cold request. Subsequent requests are fast. Keying by table name
means cache entries are naturally versioned: deploying a new GerryDB table creates a fresh entry,
and the old one becomes an orphan (no automatic cleanup).

Revisit when: Orphaned rows under old table names grow large enough to matter, or we decide to use Redis for a dedicated cache framework.

[nofurtherinformation]

In the interest of some bugfixes, this was merged in early.