MOCCA/docs/architecture.md

Architecture

MOCCA keeps a small public surface:

• mocca::SimulationConfig describes one cascade run as typed JSON-backed data.
• mocca::run_simulation() validates the config, runs the kernel, and returns a structured result artifact.
• mocca is the command-line wrapper around that library API.

Internally, the code is split into a few focused layers:

• api.cpp: JSON parsing and artifact serialization
• config_bridge.cpp: conversion from the public schema into the internal kernel state
• physics_engine.cpp: matrix elements, transition rates, and atomic-model preparation
• kernel.cpp: cascade propagation and state/line collection
• line_codec.cpp: packed line bookkeeping and decoding
• embedded_tables.cpp: compiled-in coefficient tables

The modern public interface deliberately avoids the historical card vocabulary. The old deck format survives only in the optional translator helper.