Dev guide
=========

This section is for contributors, maintainers, and advanced users who want to
understand how MARIO is organized internally.

The goal is not only to explain how to change the code, but also to explain
how the main subsystems fit together: where parsing stops, where compute logic
starts, how scenarios and matrices are stored, and which modules own high-level
operations such as plotting, export, aggregation, or shocks.

If you are trying to read the codebase efficiently, start with:

* :doc:`architecture_overview` for the package layout and the main execution
   boundaries;
* :doc:`parsers` for the ingestion path from raw sources to ``Database``;
* :doc:`compute_layer` for the catalog/resolver/formula model used to build
   matrices on demand.

If you already know which slice you need to touch, use this shorter path:

* parser work: :doc:`parsers`, then :doc:`realdata_fixtures` and
  :doc:`testing_strategy`;
* compute semantics or matrix availability: :doc:`compute_layer`, then
  :doc:`adding_new_matrices` and :doc:`testing_strategy`;
* documentation or notebook-backed pages: :doc:`documentation`;
* broad repository orientation: :doc:`architecture_overview` first.

.. toctree::
   :maxdepth: 1

   architecture_overview
   parsers
   compute_layer
   adding_new_matrices
   documentation
   testing_strategy
   realdata_fixtures

