Architecture

SPM-Kit keeps numerical behavior in a presentation-independent core. The CLI, Fathom, notebooks, and third-party applications orchestrate the same public models and analysis functions; they do not carry alternative scientific implementations.

Figure 1. Dependency direction and the main public data path. The diagram is generated by scripts/gen_theory_diagrams.py.

Dependency boundary

cli/  ─┐
       ├──▶ core/ ◀── instrument files, arrays, parameters
gui/  ─┘

• core/ does not import from cli/ or gui/.
• the CLI and Fathom import public Core interfaces;
• parsers live under core.io, calculations under core.analysis, and serialization under the export/report layers;
• companion repositories communicate through files, manifests, commands, and public packages rather than private module imports.

Core layers

Layer	Responsibility	Typical contract
core.io	detect and read supported variants	path → SPMData or force-data model
core.models	carry arrays, units, dimensions, direction, and metadata	immutable typed values
core.analysis	leveling, statistics, spectral, force, KPFM, grain, and resonance work	model + explicit parameters → result
core.export, reports	serialize inspectable artifacts	result → CSV, JSON, HDF5, image, or report
cli	stable shell orchestration	command arguments → files and terminal summary
gui / Fathom	interactive orchestration	user selection → Core call → visual result

Public boundary

from spmkit import load
from spmkit.core.analysis import kpfm, leveling, roughness, spectral

scan = load("scan.nid")
leveled = leveling.plane_fit(scan["Z-Axis"])
stats = roughness.statistics(leveled)

The object model retains measurement units and lateral ranges. An analysis result can only be interpreted within those units, the declared preprocessing, and the calibration state of the input.

Ecosystem boundary

• Fathom invokes Core through public interfaces.
• Data Hunter records candidate datasets and provenance; it does not certify them or feed them automatically into a campaign.
• Phantoms generates truth-bearing fixtures independently of the analyzer.
• Validation treats an installed SPM-Kit command or package as the system under test and can consume frozen Phantom artifacts.

This direction is scientifically important: the analyzer under test must not generate its own expected answer. See the artifact contracts and implementation map.