Architecture Overview#
Cross-cutting architecture notes that complement the per-package pages and the contributor recipes. Open these pages when the question is "where does this responsibility live" or "which layer should I change", rather than "how does one package work".
For the entry point of the developer section, see Architecture and Developer Guide. For one focused page per subpackage, see Per-Package Reference. For step-by-step extension recipes, see How-to Recipes.
Foundations#
How a TOML payload becomes a persisted run. The reasoning behind the package boundaries and the layer matrix.
Canonical patterns reused across the codebase: SolverAdapter, Step, Figure, DataManager, ProcessSpatial, and friends.
Recommended package-by-package reading paths through the source tree.
The three-level v2 layout: machine global index, workspace input cache, per-project simulation catalog. Why the split exists.
Contracts and integration#
Alembic-like migration runner that applies versioned SQL
migrations on every catalog DuckDB plus the
ZARR_SCHEMA_VERSION and PARQUET_SCHEMA_VERSION pins.
CatalogBackend Protocol, SimulationStore Protocol, and
the field registry consumed by the hmp.read facade.
JSON Schema export, OpenAPI 3.1 wrapper, and the partial-validator contract that any UI integration consumes.
The test ladder: unit, integration, regression, validation, MMS, solver sanity, calibration twins, with the role and command per family.
Snapshot of the collected pytest suite: counts by family, largest unit-test areas, validation subsets, and regression coverage.