Skip to contents

Architecture: an interactive map of garry

architecture.Rmd

garry is a lazy raster engine: verbs build an R-native compute graph, a planner fuses it into schedulable stages, and executors run those stages as JIT-compiled XLA kernels (via anvl) over GDAL-read chunks (via gdalraster). This article maps that structure interactively at two zoom levels. Both graphs are generated by static analysis of the package sources (package-graph/build_graph.R in the repository); nothing here is hand-drawn, so the maps cannot drift from the code.

The exported API surface

Every node below is an exported function, colour-coded by subsystem. An edge A -> B means calling A reaches B, possibly through internal code; edges to the gold triangle (anvl, the XLA compiler frontend) and the green square (gdalraster, GDAL IO) show which verbs ultimately touch which backend. Click a node to highlight its one-hop neighbourhood, use the dropdowns to jump to a function or filter a subsystem, and scroll to zoom.

Two things are worth reading directly off this graph. First, the lazy-verb layer (lazy_map(), focal(), reduce_over(), and friends) reaches neither backend: building a pipeline touches no data and compiles nothing. Second, everything that does reach anvl or GDAL funnels through the execution verbs (collect(), materialise(), preview(), write_tif()), which is the lazy contract made visible.

The full internal call graph

The map below is the same analysis over every top-level definition in the package: functions, S7 classes (boxes), generics (ellipses) and methods (hexagons), with dashed edges for S7 dispatch. It exists for contributors; users never need it, but it answers structural questions quickly. Where does the anvl boundary sit? Every gold edge originates in ops.R (the g_* vocabulary), a rule enforced by a test. Which subsystems are large? Node size tracks line count, so the scheduler and the GDAL adapter stand out immediately.

Subsystems

The colour groups in both graphs correspond to the package’s subsystems:

  • IR & graph: the node types, the g_* op vocabulary, the graph container, and the planner passes that fuse nodes into stages.
  • Grid & geometry: GridSpec, chunk grids, and grid construction helpers. Every lazy object is pinned to a grid; planning is grid-identity-trivial by design.
  • Execution: collect() down through the scheduler, daemon pool, and the direct composite executors.
  • IO & GDAL: the gdalraster adapter, dataset/STAC construction, and materialisation.
  • Models & kernels: OmniCloudMask, the Kalman and Hampel smoothers, band projection, and dequantisers.
  • Viz & UX: draw(), preview(), and task reports.

Regenerating

Both graphs, plus a report of the exact anvl functions garry calls, are rebuilt from source with:

# from the package root
source("package-graph/build_graph.R")

The script parses R/*.R without evaluating it, so it runs on any machine with visNetwork and igraph installed.