Architecture
============

REVISE is organized around a single public orchestration API and a fixed
reconstruction lifecycle. Profiles in ``revise/revise.yaml`` select the route;
registries map that route to concrete platform adapters, confounding-factor
strategies, OT solver markers, and local reconstruction strategies.

System Map
----------

.. code-block:: text

   REVISEPipeline.run()
   |-- load revise/revise.yaml
   |-- merge defaults, profile, runtime/io overrides, and set_overrides
   |-- resolve platform adapter, confounding strategy, and OT solver
   |-- create PipelineContext and run directory
   `-- delegate to UnifiedReconstructionPipeline
       |-- validate_inputs
       |-- global_anchoring
       |-- prepare_local_units
       |-- build_graph
       |-- build_ot_problem
       |-- solve_ot
       |-- update_expression
       |-- finalize_svc
       `-- evaluate_if_needed

Public Entry Point
------------------

``revise.framework.REVISEPipeline`` is the stable user-facing API. It performs
configuration resolution, route inference, metadata writing, deterministic seed
setup, lazy strategy initialization, and dry-run validation.

When installed from PyPI, ``REVISEPipeline()`` loads the packaged
``revise.yaml`` automatically. Source-tree scripts may still pass
``config_path="revise/revise.yaml"`` for compatibility.

Configuration Surface
---------------------

``revise/revise.yaml`` is the source of truth for runtime routes and
paper-facing defaults. New routing behavior should normally be added there
rather than scattered through scripts.

.. list-table::
   :header-rows: 1
   :widths: 1 2

   * - YAML section
     - Responsibility
   * - ``defaults``
     - Baseline runtime, IO, preprocessing, graph, OT, plotting,
       reconstruction, benchmark, sc-SVC, and imputation settings.
   * - ``router``
     - Maps ``platform`` plus ``confounding`` to mode, task, SVC kind,
       strategy, platform adapter, confounding strategy, and OT solver.
   * - ``profiles``
     - Named presets used by wrapper scripts, notebooks, and direct API calls.
   * - ``locked_params``
     - Guardrail for low-level OT settings that should not drift accidentally
       during paper and rebuttal-style runs.

Unified Lifecycle
-----------------

``revise.recon.pipeline.UnifiedReconstructionPipeline`` owns the fixed stage
order. Strategy implementations customize stage internals but do not change the
topology of the lifecycle. This makes application and benchmark routes easier
to compare because each run records the same stage trace in provenance.

.. list-table::
   :header-rows: 1
   :widths: 1 2

   * - Stage
     - Purpose
   * - ``validate_inputs``
     - Check required files, route compatibility, and strategy context.
   * - ``global_anchoring``
     - Align spatial data and the single-cell reference at the global level.
   * - ``prepare_local_units``
     - Build local reconstruction units for the selected SVC route.
   * - ``build_graph``
     - Construct spatial/expression neighborhood graphs.
   * - ``build_ot_problem`` and ``solve_ot``
     - Form and solve the optimal transport problem.
   * - ``update_expression``
     - Transfer or refine molecular signals.
   * - ``finalize_svc``
     - Produce the ``SVC`` result carrier and write canonical artifacts.
   * - ``evaluate_if_needed``
     - Compute normalized benchmark metrics when evaluation is enabled.

Registries and Plugins
----------------------

The backend separates route selection from implementation details:

- ``StrategyRegistry`` selects local refinement strategies such as
  ``SpSvcApplicationStrategy``, ``ScSvcApplicationStrategy``,
  ``ScSvcSrBenchmarkStrategy``, and ``ScSvcImputeBenchmarkStrategy``.
- ``PluginRegistry`` selects platform adapters, confounding-factor strategies,
  and OT solver route markers.
- Analysis services consume the unified ``SVC`` result carrier and keep
  notebook-facing downstream workflows compatible.

Run Artifacts
-------------

Every unified run writes metadata that should be inspected before comparing
results:

.. code-block:: text

   <output_root>/<sample>/<route>/<case-or-run>/
   |-- merged_config.json
   |-- provenance.json
   `-- artifacts/
       |-- sp_svc.h5ad
       |-- sc_svc_expr.h5ad
       `-- sc_svc_spatial.h5ad

Benchmark routes additionally write ``metrics_normalized.csv`` when evaluation
is enabled. Application wrappers publish notebook-compatible copies under
``output/`` while keeping canonical artifacts in the resolved run directory.

Extension Checklist
-------------------

When adding a route or strategy, keep the change local to the existing
extension points:

1. Add or update a profile in ``revise/revise.yaml``.
2. Add a router entry if the platform/confounding pair is new.
3. Register any new strategy or plugin in ``revise/backend/registry.py``.
4. Add a dry-run or focused validator command that proves the route resolves.
5. Document the new route in :doc:`configuration` and the relevant application
   or benchmark page.