# 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.