# insarlab/mintpy architecture

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

- Interactive diagram: https://gitdiagram.com/insarlab/mintpy
- Repository: https://github.com/insarlab/mintpy

## Overview

##### Project Type and Purpose
- MintPy is an open-source, Python-based CLI application and library for InSAR time-series analysis.
- It provides:
- A routine workflow entry-point (`smallbaselineApp.py`) to ingest stacks of interferograms from various external formats (ISCE, ARIA, FRInGE, HyP3, GMTSAR, SNAP, GAMMA, ROI_PAC), perform time-series inversion, error corrections, and output 2D+time ground displacement.
- An extensible toolbox of individual CLI scripts for data loading, processing steps, visualization, and exporting results (e.g., KMZ, GDAL, QGIS).
- A modular Python library (`src/mintpy`) exposing core classes and utilities for advanced users to build custom workflows.

##### High-Level File-Structure Analysis
- Top-Level Artifacts
- CI/CD configs (.circleci/, .github/workflows/) and Dockerfile for automated builds, tests, packaging (PyPI, conda, Docker).
- Documentation (docs/, README, mkdocs.yml, Read the Docs integration).
- Scripts/ folder with convenience wrappers for common shell workflows.
- src/mintpy/: The heart of the system, broken into subpackages:
– cli/: one CLI module per command (e.g., load_data, geopcode, plot_network, save_kmz).
– data/: static resources (colormaps, plate boundary files, lookup tables).
– defaults/: default configuration templates and YAML settings.
– objects/: domain objects (e.g., Stack, Sensor, EulerPole).
– stdproc/: core interferogram processing routines.
– simulation/: synthetic data generation for testing and validation.
– utils/: helper functions (I/O, numerical solvers, plotting).
– workflow/: orchestrates multi-step pipelines.
– main entrypoint (`__main__.py`, smallbaselineApp.py).
- tests/: unit and integration tests.
- packaging files (pyproject.toml, requirements.txt, MANIFEST.in).

##### Key Components & Their Relationships
- User / Operator
- Invokes CLI commands or scripts (e.g., `smallbaselineApp.py`, `info.py`, `view.py`).
- CLI Layer
- Parses arguments, loads default + custom configs, then calls into the workflow or individual modules.
- Workflow Manager (`mintpy.workflow`)
- Reads the directory structure & metadata, sequences processing steps: load_data → reference_point → inversion → coherence calculation → corrections (LO drift, tropo, DEM error, ramp removal) → velocity estimation → output.
- Processing Modules
- stdproc/: multilook, filtering, inversion solvers; simulation/: synthetic interferograms; dem_error, diff, geocode, etc.
- Each module implements one step, imports utils and objects.
- Core Libraries
- objects/: encapsulate data structures (Stack, time series matrices, network graphs).
- utils/: file I/O (HDF5, shapefiles), numerical routines (l1, lstl1 solvers), plotting (matplotlib, dygraphs).
- Data Resources
- data/: static colormaps, plate boundary definitions, default templates.
- Output & Visualization
- save_* modules write HDF5, GeoTIFF, KMZ, QGIS project files; plot_* modules generate interactive and static plots.
- External Integrations
- Reads input from multiple third-party InSAR processing tools; can be deployed via Docker, conda, PyPI.
- CI/CD & Packaging
- Automated pipelines build, test, lint, publish to PyPI and Docker registry.
- Documentation & Tests
- docs/ site, API references, examples; tests/ ensure functional correctness.

##### Architectural Patterns & Design Principles
- Layered Architecture:
- CLI/Script layer → Workflow orchestration → Processing modules → Utility & data modules → External I/O.
- Modular CLI: each command is a self-contained module under `cli/` – easy to extend with new commands.
- Pipeline Orchestration: `workflow/` subpackage manages stepwise execution, enabling partial reruns, custom recipes, and templating.
- Separation of Concerns:
- Data classes (objects/) vs. numerical routines (utils/solvers) vs. I/O and config (defaults/, data/).
- Plug-in-style approach: new processing steps can be added by dropping a module into `src/mintpy/cli` and registering it.

##### Final Reminders
- Essential modules without overcrowding: group related subpackages in containers (e.g., “Processing Modules” blocks).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interface
    subgraph "User Interface"
        UI["Shell Scripts"]:::user
        click UI "https://github.com/insarlab/mintpy/tree/main/scripts/"
    end

    %% CLI Entry-Point & Parser
    subgraph "CLI Entry-Point & Parser"
        Main["__main__.py"]:::user
        click Main "https://github.com/insarlab/mintpy/blob/main/src/mintpy/__main__.py"
        CLI["CLI Commands"]:::user
        click CLI "https://github.com/insarlab/mintpy/tree/main/src/mintpy/cli/"
        SBA["smallbaselineApp.py"]:::user
        click SBA "https://github.com/insarlab/mintpy/blob/main/src/mintpy/cli/smallbaselineApp.py"
        Info["info.py"]:::user
        click Info "https://github.com/insarlab/mintpy/blob/main/src/mintpy/cli/info.py"
        View["view.py"]:::user
        click View "https://github.com/insarlab/mintpy/blob/main/src/mintpy/cli/view.py"
    end

    %% Workflow Orchestrator
    subgraph "Workflow Orchestrator"
        WF["mintpy.workflow"]:::core
        click WF "https://github.com/insarlab/mintpy/tree/main/src/mintpy/workflow/"
    end

    %% Processing Modules
    subgraph "Processing Modules"
        Std["Standard Processing"]:::core
        click Std "https://github.com/insarlab/mintpy/tree/main/src/mintpy/stdproc/"
        Sim["Simulation"]:::core
        click Sim "https://github.com/insarlab/mintpy/tree/main/src/mintpy/simulation/"
    end

    %% Core Libraries
    subgraph "Core Libraries"
        Obj["Domain Objects"]:::core
        click Obj "https://github.com/insarlab/mintpy/tree/main/src/mintpy/objects/"
        Utils["Utilities"]:::core
        click Utils "https://github.com/insarlab/mintpy/tree/main/src/mintpy/utils/"
    end

    %% Data & Config
    subgraph "Data & Config"
        Data["Static Data"]:::data
        click Data "https://github.com/insarlab/mintpy/tree/main/src/mintpy/data/"
        Defs["Default Templates"]:::data
        click Defs "https://github.com/insarlab/mintpy/tree/main/src/mintpy/defaults/"
    end

    %% Output & Visualization
    subgraph "Output & Visualization"
        OutLib["Library Modules"]:::output
        click OutLib "https://github.com/insarlab/mintpy/blob/main/src/mintpy/save_*.py"
        OutCLI["CLI Commands"]:::output
        click OutCLI "https://github.com/insarlab/mintpy/blob/main/src/mintpy/cli/save_*.py"
    end

    %% Legacy Code
    Legacy["Legacy Code"]:::core
    click Legacy "https://github.com/insarlab/mintpy/tree/main/src/mintpy/legacy/"

    %% Packaging & CI/CD
    subgraph "Packaging & CI/CD"
        Pack["Packaging Config"]:::external
        click Pack "https://github.com/insarlab/mintpy/blob/main/pyproject.toml"
        click Pack "https://github.com/insarlab/mintpy/blob/main/requirements.txt"
        click Pack "https://github.com/insarlab/mintpy/blob/main/MANIFEST.in"
        click Pack "https://github.com/insarlab/mintpy/tree/main/Dockerfile"
        CID["CI/CD Pipelines"]:::external
        click CID "https://github.com/insarlab/mintpy/blob/main/.circleci/config.yml"
        click CID "https://github.com/insarlab/mintpy/tree/main/.github/workflows/"
    end

    %% Documentation & Tests
    Docs["Documentation"]:::external
    click Docs "https://github.com/insarlab/mintpy/tree/main/docs/"
    click Docs "https://github.com/insarlab/mintpy/blob/main/mkdocs.yml"
    click Docs "https://github.com/insarlab/mintpy/blob/main/.readthedocs.yaml"
    Tests["Tests"]:::external
    click Tests "https://github.com/insarlab/mintpy/tree/main/tests/"

    %% Connections
    UI --> Main
    Main --> CLI
    CLI --> SBA
    CLI --> Info
    CLI --> View
    CLI --> WF
    WF --> Std
    WF --> Sim
    Std --> Obj
    Std --> Utils
    Sim --> Obj
    Sim --> Utils
    WF --> Data
    WF --> Defs
    WF --> OutLib
    WF --> OutCLI
    WF --> Legacy
    WF --- Pack
    WF --- CID
    Pack --- CID
    Pack --- Docs
    CID --- Tests

    %% Styles
    classDef user fill:#9f6,stroke:#393,stroke-width:1px;
    classDef core fill:#6cf,stroke:#039,stroke-width:1px;
    classDef data fill:#fc6,stroke:#a60,stroke-width:1px;
    classDef output fill:#c6f,stroke:#60a,stroke-width:1px;
    classDef external fill:#ccc,stroke:#666,stroke-width:1px;
```
