# ibm/terratorch architecture

> Architecture diagram of the GitHub repository ibm/terratorch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ibm/terratorch
- Repository: https://github.com/ibm/terratorch

## Overview

##### Project Type & Purpose
- TerraTorch is an open-source Python domain library (not a monolithic application) built on top of PyTorch Lightning and TorchGeo.
- Its goal is to provide a flexible fine-tuning framework for geospatial foundation models (Prithvi, TerraMind, SatMAE, etc.), offering ready-to-use datasets, datamodules, model factories, tasks, and a CLI.

##### File Structure & Architectural Patterns
- Top-level packaging:
- terratorch/ – the core library
– __main__.py, cli_tools.py, validate_config.py (entrypoints & utilities)
– datamodules/, datasets/ (Lightning-style DataModules & PyTorch Datasets)
– models/ (backbones, decoders, heads, factories)
– tasks/ (training/inference tasks, loss handlers, optimizer factories)
– registry/ (central registries for backbones, decoders, datamodules)
– samplers/, utils/ (supporting utilities)
- examples/, docs/, tests/, integrationtests/ (usage samples, docs, CI tests)
- Architectural pattern:
- Layered design separating
– Interface layer (CLI, notebooks, YAML configs)
– Orchestration layer (Tasks that glue DataModules, Models, and Lightning Trainer)
– Model layer (Model factories assemble backbones → necks → heads/decoders)
– Data layer (DataModules wrap datasets and transforms)
- Factory & Registry pattern for plug-and-play components
- Lightning plugin pattern: tasks implement step(), configure_optimizers() and hand off to LightningTrainer

##### Key Components & Their Relationships
a. Interface Components
- CLI (terratorch CLI via __main__.py & cli_tools.py)
- Config files (YAML) loaded by validate_config.py
- Notebooks / Python API that call the same internals
b. Orchestration Layer
- Task classes (terratorch.tasks.*) define prepare_data(), train/validation steps, inference loops
- These take as input: a DataModule instance + a Model (from factory) + optimizer/loss
- Hand off to PyTorch Lightning’s Trainer
c. Data Layer
- Datasets (terratorch.datasets.*) implement raw geospatial data loading & transforms
- Datamodules (terratorch.datamodules.*) wrap Datasets into train/val/test DataLoaders
d. Model Layer
- Backbones (terratorch.models.backbones.*) – pre-trained foundation model encoders
- Decoders/Heads (terratorch.models.decoders.*, heads/) – task-specific output modules
- Model Factories (encoder_decoder_factory.py, full_model_factory.py, smp_model_factory.py, etc.) use registries to pair backbones + decoders + heads
e. Registry & Utilities
- registry/ ensures decoupling: registering new backbones, decoders, datasets without editing core
- cli_tools & validate_config ensure correct wiring of components from YAML to Python objects
f. External Dependencies
- PyTorch & PyTorch Lightning (training runtime)
- TorchGeo (geospatial foundation models & datasets)
- Hugging Face Hub (model weights)
- SMP / mmsegmentation / timm (backbone & decoder providers)
- GDAL (geospatial I/O)

##### Architectural Patterns & Design Principles
- Separation of Concerns: interface vs orchestration vs data vs model
- Factories & Registries to enable plug-in extensibility
- Lightning plugin pattern (Tasks delegate actual training loops)
- Declarative configuration (YAML → Python objects via validate_config/cli_tools)

##### Essential Elements to Capture
- Interfaces: CLI & Configs → loaders (validate_config.py, cli_tools.py)
- Orchestration: Task classes + Lightning Trainer
- Data Flow: DataModule → Dataset → on-disk geospatial files via GDAL
- Model Construction: Registry → Factory → Backbone + Decoder + Head → PyTorch model
- External Integrations: TorchGeo, timm, SMP, Hugging Face, PyTorch Lightning

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Interface Layer
    subgraph "Interface Layer"
        direction TB
        CLI["CLI (terratorch CLI)"]:::interface
        ConfigLoader["Config Loader\n(validate_config.py)"]:::interface
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        direction TB
        Tasks["Task Module\n(terratorch.tasks)"]:::orchestration
        Trainer["Lightning Trainer\n(PyTorch Lightning)"]:::orchestration
    end

    %% Core Layer
    subgraph "Core Layer"
        direction TB
        DataLayer["Data Layer\nDatamodules & Datasets"]:::core
        ModelLayer["Model Layer\nFactories, Backbones, Decoders, Heads"]:::core
        Registry["Registry"]:::core
        Utils["Utils & Samplers"]:::core
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        Torch["PyTorch & Lightning"]:::external
        TorchGeo["TorchGeo"]:::external
        HF["Hugging Face Hub"]:::external
        GDAL["GDAL I/O"]:::external
        SMP["SMP / mmsegmentation / timm"]:::external
    end

    %% Connections
    CLI -->|"loads YAML & calls"| ConfigLoader
    ConfigLoader -->|"instantiates"| Tasks
    Tasks -->|"uses DataModule"| DataLayer
    DataLayer -->|"loads Dataset"| DataLayer
    Tasks -->|"builds Model via Factory"| ModelLayer
    ModelLayer -->|"registers components"| Registry
    Tasks -->|"hands off to"| Trainer
    Trainer -->|"runtime on"| Torch
    Trainer -->|"uses Loader"| DataLayer
    ModelLayer -->|"fetches weights"| HF
    DataLayer -->|"reads files via"| GDAL
    ModelLayer -->|"imports models from"| TorchGeo
    ModelLayer -->|"imports backbones/decoders from"| SMP

    %% Click Events
    click CLI "https://github.com/ibm/terratorch/blob/main/terratorch/__main__.py"
    click CLI "https://github.com/ibm/terratorch/blob/main/terratorch/cli_tools.py"
    click ConfigLoader "https://github.com/ibm/terratorch/blob/main/terratorch/validate_config.py"
    click Tasks "https://github.com/ibm/terratorch/blob/main/terratorch/tasks/base_task.py"
    click Tasks "https://github.com/ibm/terratorch/blob/main/terratorch/tasks/classification_tasks.py"
    click Tasks "https://github.com/ibm/terratorch/blob/main/terratorch/tasks/regression_tasks.py"
    click Tasks "https://github.com/ibm/terratorch/blob/main/terratorch/tasks/segmentation_tasks.py"
    click Tasks "https://github.com/ibm/terratorch/blob/main/terratorch/tasks/object_detection_task.py"
    click Tasks "https://github.com/ibm/terratorch/blob/main/terratorch/tasks/reconstruction_tasks.py"
    click Tasks "https://github.com/ibm/terratorch/blob/main/terratorch/tasks/eccc_downscaling_task.py"
    click Tasks "https://github.com/ibm/terratorch/blob/main/terratorch/tasks/wxc_downscaling_task.py"
    click Tasks "https://github.com/ibm/terratorch/blob/main/terratorch/tasks/wxc_task.py"
    click Tasks "https://github.com/ibm/terratorch/blob/main/terratorch/tasks/multilabel_classification_tasks.py"
    click Tasks "https://github.com/ibm/terratorch/blob/main/terratorch/tasks/tiled_inference.py"
    click Tasks "https://github.com/ibm/terratorch/blob/main/terratorch/tasks/optimizer_factory.py"
    click Tasks "https://github.com/ibm/terratorch/blob/main/terratorch/tasks/loss_handler.py"
    click DataLayer "https://github.com/ibm/terratorch/tree/main/terratorch/datamodules"
    click DataLayer "https://github.com/ibm/terratorch/tree/main/terratorch/datasets"
    click ModelLayer "https://github.com/ibm/terratorch/tree/main/terratorch/models/backbones"
    click ModelLayer "https://github.com/ibm/terratorch/tree/main/terratorch/models/decoders"
    click ModelLayer "https://github.com/ibm/terratorch/tree/main/terratorch/models/heads"
    click ModelLayer "https://github.com/ibm/terratorch/blob/main/terratorch/models/encoder_decoder_factory.py"
    click ModelLayer "https://github.com/ibm/terratorch/blob/main/terratorch/models/full_model_factory.py"
    click ModelLayer "https://github.com/ibm/terratorch/blob/main/terratorch/models/generic_model_factory.py"
    click ModelLayer "https://github.com/ibm/terratorch/blob/main/terratorch/models/generic_unet_model_factory.py"
    click ModelLayer "https://github.com/ibm/terratorch/blob/main/terratorch/models/prithvi_model_factory.py"
    click ModelLayer "https://github.com/ibm/terratorch/blob/main/terratorch/models/satmae_model_factory.py"
    click ModelLayer "https://github.com/ibm/terratorch/blob/main/terratorch/models/wxc_model_factory.py"
    click ModelLayer "https://github.com/ibm/terratorch/blob/main/terratorch/models/smp_model_factory.py"
    click ModelLayer "https://github.com/ibm/terratorch/blob/main/terratorch/models/timm_model_factory.py"
    click ModelLayer "https://github.com/ibm/terratorch/blob/main/terratorch/models/object_detection_model_factory.py"
    click ModelLayer "https://github.com/ibm/terratorch/blob/main/terratorch/models/clay_model_factory.py"
    click Registry "https://github.com/ibm/terratorch/blob/main/terratorch/registry/registry.py"
    click Registry "https://github.com/ibm/terratorch/blob/main/terratorch/registry/custom_registry.py"
    click Registry "https://github.com/ibm/terratorch/blob/main/terratorch/registry/timm_registry.py"
    click Registry "https://github.com/ibm/terratorch/blob/main/terratorch/registry/smp_registry.py"
    click Registry "https://github.com/ibm/terratorch/blob/main/terratorch/registry/mmseg_registry.py"
    click Utils "https://github.com/ibm/terratorch/blob/main/terratorch/utils.py"
    click Utils "https://github.com/ibm/terratorch/blob/main/terratorch/io/file.py"
    click Utils "https://github.com/ibm/terratorch/blob/main/terratorch/samplers/single.py"
    click Utils "https://github.com/ibm/terratorch/blob/main/terratorch/samplers/__init__.py"

    %% Styles
    classDef interface fill:#D6EAF8,stroke:#21618C,color:#1B2631;
    classDef orchestration fill:#D5F5E3,stroke:#1D8348,color:#145A32;
    classDef core fill:#FCF3CF,stroke:#B7950B,color:#7D6608;
    classDef external fill:#F2F3F4,stroke:#B3B6B7,color:#424949;
```
