Package Architecture

This page documents the internal architecture used to implement OpenPinch.PinchProblem and OpenPinch.PinchWorkspace. Module ownership and dependency direction are enforced by tests.

Owner Responsibilities

Owner	Responsibility	May depend on
`domain`	Business state, invariants, arithmetic, indexing, parent-owned records	domain peers and third-party numerical/value libraries
`contracts`	Request, response, report, workspace, HPR, and HEN wire models	contracts and domain
`optimisation`	Reusable scalar optimisation models, candidates, execution, and backends	optimisation peers, NumPy, and SciPy
`adapters`	Filesystem formats, optional-dependency checks, and infrastructure translation	adapters, contracts, domain, and resource lookup
`analysis`	Deterministic engineering calculations, HPR, HEN, and numerical services	analysis, contracts, domain, optimisation, and explicit adapter leaves
`application`	Use-case orchestration, caches, replay, workspaces, and coordination	inward owners and lazy presentation calls
`presentation`	Reports, tables, figures, dashboards, diagrams, and exports	presentation, analysis, adapters, contracts, and domain

Dependency Direction

Dependencies point toward domain and contracts. Domain never imports an outer owner. Contracts do not import application, analysis, adapters, optimisation, or presentation. Optimisation is reusable without importing heat-pump code. Application coordinates concrete owners but does not import solver backends, Plotly, Streamlit, or filesystem classes directly. Optional dependencies are loaded only by the leaf that owns the feature.

The architecture test records a small exact set of existing cross-layer HEN service and type dependencies. The test fails if those exceptions spread to a new file. This makes remaining coupling visible rather than silently treating it as a general dependency direction.

Execution Flow

The supported request follows this sequence:

PinchProblem validates input through contracts.
application constructs and coordinates the problem use case.
analysis performs deterministic targeting using domain state.
presentation and adapters shape outputs only when requested by an internal advanced workflow.
PinchProblem caches the validated output contract for observation.

Optimisation Boundary

OpenPinch.optimisation accepts an immutable scalar problem, method, and options and returns ranked candidates. Heat-pump analysis translates its thermodynamic objective at one explicit adapter. Other services can reuse the same optimiser without importing any HPR module. No mutable backend registry or service locator is used.

Private Runtime Records

Stream segments, exchanger period states, exchanger area slices, process-MVR records, multiperiod cases, graph build specifications, dashboard state, and solver records belong to their parent or service owner. They may be inspected through parent results, but their classes are not external construction APIs.

Test Architecture

Tests mirror observable owners under tests/e2e, tests/application, tests/domain, tests/analysis, tests/optimisation, tests/adapters, tests/presentation, and tests/contracts. Architecture and packaging tests are separate. Private-module tests are kept for mathematical kernels, solver equation order, explicit architecture rules, or focused failure localization.

The end-to-end main suite is the authoritative compatibility suite. Property tests use Hypothesis with seed 20260715 while retaining shrinking.