Architecture

AMMM3 is structured so that the public MMM API stays small while the implementation can evolve behind stable seams. The most important rule is that PanelMMM is a facade, not the place where new core behaviour should accumulate.

For the complete module map, read ARCHITECTURE.md in the repository root. This page summarises the parts that matter most when you are deciding where to put new code.

Design Principles

  1. PanelMMM stays thin. Constructor normalisation, data prep, graph construction, prediction, calibration, runtime helpers, and serialisation live under src/abacus/mmm/models/.
  2. Compute comes before presentation. Diagnostics, summaries, and plotting should consume structured outputs from the model layer rather than embedding analytical logic in presentation code.
  3. Dependencies flow downward. Shared root infrastructure can be imported by MMM modules, but MMM-specific modules should not leak back into the shared layer.
  4. Compatibility is deliberate. If you move imports or rename internals, keep facades or compatibility shims where public usage would otherwise break.

High-Level Package Layers

LayerPurposeExamples
Public facadesStable user-facing entry pointsabacus.mmm.panel, abacus.mmm.plot, abacus.mmm.summary
Panel implementation seamsCore panel behaviourabacus.mmm.models.panel_config, panel_build, panel_predict, panel_runtime, panel_serialize
MMM primitivesReusable modelling building blocksabacus.mmm.components, abacus.mmm.transforms, abacus.mmm.fourier, abacus.mmm.hsgp, abacus.mmm.events
Post-fit outputsDiagnostics, summaries, optimisation, plotsabacus.mmm.diagnostics, abacus.mmm.summarization, abacus.mmm.optimization, abacus.mmm.plotting
Shared rootGeneric infrastructure used across the packageabacus.modeling, abacus.prior, abacus.metrics, abacus.data, abacus.pipeline

Where New Code Goes

If you are adding…Put it in…
Constructor normalisation, dims logic, transform configurationsrc/abacus/mmm/models/panel_config.py
Data conversion, scaling, Mundlak support, prediction-data prepsrc/abacus/mmm/models/panel_data.py
PyMC graph constructionsrc/abacus/mmm/models/panel_build.py
Posterior predictive or response-curve samplingsrc/abacus/mmm/models/panel_predict.py
Serialisation or save/load compatibilitysrc/abacus/mmm/models/panel_serialize.py and shared helpers in src/abacus/modeling/io.py
Diagnostics computesrc/abacus/mmm/diagnostics/
Summary tables and exported curve summariessrc/abacus/mmm/summarization/
Static chartssrc/abacus/mmm/plotting/
Budget optimisation logicsrc/abacus/mmm/optimization/
Adstock or saturation behavioursrc/abacus/mmm/components/ and src/abacus/mmm/transforms/
Shared model-builder infrastructuresrc/abacus/modeling/

Dependency Rules

Allowed

  • Shared root modules can be imported by MMM modules.
  • src/abacus/mmm/models/ can depend on MMM primitives and shared root modules.
  • Facades such as panel.py can depend on the extracted panel modules.
  • Plotting, summaries, diagnostics, and optimisation can depend on model outputs and extracted helpers.

Avoid

  • Importing panel.py from src/abacus/mmm/models/*.
  • Adding plotting or summary logic to core model-building modules.
  • Adding MMM-specific behaviour to the shared src/abacus/modeling/ layer unless it is genuinely reusable.
  • Defaulting to panel.py for new features just because it is visible.

Practical Guidance

When you touch a feature area, check whether there is already an extracted seam for it before adding a new helper. Examples:

  • Plot behaviour should usually land in src/abacus/mmm/plotting/, not in src/abacus/mmm/plot.py.
  • Serialisation changes should usually land in src/abacus/mmm/models/panel_serialize.py, not directly in PanelMMM.
  • Time-varying parameter behaviour should use the HSGP and TVP support modules rather than embedding new logic in plotting or builders.

Before You Merge

  • Confirm the change landed in the correct layer.
  • Keep public facades thin.
  • Preserve public API compatibility unless the change is explicitly breaking.
  • Add or update tests in the matching test area.
  • Run the local verification commands described in Testing.