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

Entry Points
------------

The plugin entry point is the ``Roll`` class in ``roll.py``. It integrates with
QGIS, creates plugin actions, and launches the main application window.

The main UI lives in ``RollMainWindow`` in ``roll_main_window.py``. It loads the
Qt Designer user interface, wires menu and toolbar actions, and coordinates project,
plotting, property editing, and processing services.

Core Data Model
---------------

The survey model is centered on ``RollSurvey`` in ``roll_survey.py``.

``RollSurvey`` owns:

* survey geometry such as blocks, templates, seeds, and patterns;
* coordinate transforms and CRS handling;
* binning-related state; and
* rendering support for the plotting views.

Project files are stored as XML ``.roll`` documents. The XML structure keeps
the survey geometry and other core data model elements together in a logical
hierarchy complete with metadata such as the CRS WKT string.

Processing Model
----------------

Long-running geometry creation, binning and cfp calculations are pushed onto ``QThread`` workers.
This keeps the GUI responsive while heavy processing runs in the background.

Numeric hot paths live in ``aux_functions_numba.py`` with fallback behavior kept in
mind for environments where Numba is unavailable. 
Using Numba aims to speed up critical loops in geometry creation and binning, 
but the plugin can still function without it, albeit with potentially slower performance on large datasets.

Output and Analysis Storage
---------------------------

Analysis outputs are represented by ``RollOutput`` members in ``roll_output.py``.
Full binning writes detailed per-trace information to memory-mapped analysis
files so large datasets can be processed and inspected without forcing a full
in-memory load.

UI Composition
--------------

The main window delegates substantial UI setup to focused modules such as the
``roll_main_window_create_*`` files. Additional controllers and services handle
stateful concerns like:

* property-panel behavior;
* action enablement;
* plotting navigation and redraw reuse;
* project loading and saving; and
* import and export workflows.

QGIS Integration
----------------

QGIS integration includes:

* importing and exporting source and receiver geometry;
* exporting rasters and outlines into the active QGIS project; and
* supporting point-layer round-trips for editing outside Roll.

The plugin therefore sits between a compact internal survey definition and the
more explicit geometry and raster products consumed in QGIS.

Documentation Boundary
----------------------

The Sphinx documentation in ``help/source`` is intended to provide maintainable
project documentation. The QGIS round-trip guide is maintained directly in the
reStructuredText sources so it can be updated alongside the rest of the help.