# forestdatapartnership/whisp architecture

> Architecture diagram of the GitHub repository forestdatapartnership/whisp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/forestdatapartnership/whisp
- Repository: https://github.com/forestdatapartnership/whisp

## Overview

Whisp is a Python geospatial analysis package: users provide plot geometries, which are checked and converted for Earth Engine analysis; dataset layers are reduced to plot statistics, formatted, and can be assessed for commodity-specific forest risk. It also documents privacy-preserving local processing and faster batched processing. The App/API are a separate repository, not part of this runtime map. Internal edges are limited to relationships shown by excerpts or the source index; unsampled implementation details are not inferred.

Main entry points: [`src/openforis_whisp/stats.py`](https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/stats.py) (Statistics API), [`src/openforis_whisp/datasets.py`](https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/datasets.py) (Earth Engine layers), [`src/openforis_whisp/advanced_stats.py`](https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/advanced_stats.py) (Batched statistics), [`src/openforis_whisp/reformat.py`](https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/reformat.py) (Output formatting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Geometry Inputs"]
  node_checks["Input checks<br/>[data_checks.py]"]
  node_conversion["Geometry conversion<br/>[data_conversion.py]"]
end

subgraph group_analysis["Earth Engine Analysis"]
  node_stats["Statistics API<br/>[stats.py]"]
  node_datasets["Earth Engine layers<br/>[datasets.py]"]
  node_advanced["Batched statistics<br/>[advanced_stats.py]"]
  node_local["Local statistics<br/>[local_stats.py]"]
  node_stats_helpers["Local and core stats<br/>[advanced_stats.py]"]
end

subgraph group_results["Results and Risk"]
  node_format["Output formatting<br/>[reformat.py]"]
  node_schema["Output schemas<br/>[pd_schemas.py]"]
  node_risk["Risk assessment<br/>[risk.py]"]
end

subgraph group_processing["Processing Support"]
  node_config["Runtime configuration<br/>[config_runtime.py]"]
  node_admin["Admin lookup"]
  node_assets["Asset registry<br/>[asset_registry.py]"]
  node_control["Exception policy<br/>[control_flow.py]"]
  node_logger["Logging<br/>[logger.py]"]
end

node_user(("Package user"))
node_ee(("Google Earth Engine"))

node_user -->|"submits geometries"| node_checks
node_user -->|"runs analysis"| node_stats
node_stats -->|"converts input"| node_conversion
node_stats -->|"uses layers"| node_datasets
node_datasets -.->|"queries imagery"| node_ee
node_stats -->|"formats results"| node_format
node_advanced -->|"uses layers"| node_datasets
node_advanced -->|"formats results"| node_format
node_advanced -->|"uses conversion"| node_conversion
node_local -->|"uses layers"| node_datasets
node_local -->|"formats results"| node_format
node_local -->|"downloads imagery"| node_ee
node_format -->|"uses schemas"| node_schema
node_risk -->|"formats columns"| node_format
node_risk -->|"checks layer names"| node_datasets
node_stats -->|"reads settings"| node_config
node_datasets -->|"reads settings"| node_config
node_advanced -->|"joins admin codes"| node_admin
node_advanced -->|"logs progress"| node_logger
node_local -->|"preserves exceptions"| node_control
node_stats -->|"preserves exceptions"| node_control
node_user -.->|"manages assets"| node_assets
node_stats -.->|"assesses risk"| node_risk

click node_checks "https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/data_checks.py"
click node_conversion "https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/data_conversion.py"
click node_stats "https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/stats.py"
click node_datasets "https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/datasets.py"
click node_advanced "https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/advanced_stats.py"
click node_local "https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/local_stats.py"
click node_format "https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/reformat.py"
click node_schema "https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/pd_schemas.py"
click node_risk "https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/risk.py"
click node_config "https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/parameters/config_runtime.py"
click node_admin "https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/parameters/lookup_gaul1_admin.py"
click node_assets "https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/asset_registry.py"
click node_control "https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/control_flow.py"
click node_logger "https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/logger.py"
click node_stats_helpers "https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/advanced_stats.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_checks,node_conversion,node_user toneBlue
class node_stats,node_datasets,node_advanced,node_local,node_stats_helpers toneAmber
class node_format,node_schema,node_risk toneMint
class node_config,node_admin,node_assets,node_control,node_logger toneRose
class node_ee toneIndigo
```

## Components

### Geometry Inputs

- [Input checks](https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/data_checks.py): `src/openforis_whisp/data_checks.py`
- [Geometry conversion](https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/data_conversion.py): `src/openforis_whisp/data_conversion.py`

### Earth Engine Analysis

- [Statistics API](https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/stats.py): `src/openforis_whisp/stats.py`
- [Earth Engine layers](https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/datasets.py): `src/openforis_whisp/datasets.py`
- [Batched statistics](https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/advanced_stats.py): `src/openforis_whisp/advanced_stats.py`
- [Local statistics](https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/local_stats.py): `src/openforis_whisp/local_stats.py`
- [Local and core stats](https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/advanced_stats.py): `src/openforis_whisp/advanced_stats.py`

### Results and Risk

- [Output formatting](https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/reformat.py): `src/openforis_whisp/reformat.py`
- [Output schemas](https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/pd_schemas.py): `src/openforis_whisp/pd_schemas.py`
- [Risk assessment](https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/risk.py): `src/openforis_whisp/risk.py`

### Processing Support

- [Runtime configuration](https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/parameters/config_runtime.py): `src/openforis_whisp/parameters/config_runtime.py`
- [Admin lookup](https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/parameters/lookup_gaul1_admin.py): `src/openforis_whisp/parameters/lookup_gaul1_admin.py`
- [Asset registry](https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/asset_registry.py): `src/openforis_whisp/asset_registry.py`
- [Exception policy](https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/control_flow.py): `src/openforis_whisp/control_flow.py`
- [Logging](https://github.com/forestdatapartnership/whisp/blob/main/src/openforis_whisp/logger.py): `src/openforis_whisp/logger.py`

### Other components

- **Package user**
- **Google Earth Engine**

## Connections

- Package user → Input checks: submits geometries (evidence: `README.md`)
- Package user → Statistics API: runs analysis (evidence: `README.md`)
- Statistics API → Geometry conversion: converts input (evidence: `src/openforis_whisp/stats.py`)
- Statistics API → Earth Engine layers: uses layers (evidence: `src/openforis_whisp/stats.py`)
- Earth Engine layers → Google Earth Engine: queries imagery
- Statistics API → Output formatting: formats results (evidence: `src/openforis_whisp/stats.py`)
- Batched statistics → Earth Engine layers: uses layers (evidence: `src/openforis_whisp/advanced_stats.py`)
- Batched statistics → Output formatting: formats results (evidence: `src/openforis_whisp/advanced_stats.py`)
- Batched statistics → Geometry conversion: uses conversion (evidence: `src/openforis_whisp/advanced_stats.py`)
- Local statistics → Earth Engine layers: uses layers (evidence: `src/openforis_whisp/local_stats.py`)
- Local statistics → Output formatting: formats results (evidence: `src/openforis_whisp/local_stats.py`)
- Local statistics → Google Earth Engine: downloads imagery (evidence: `src/openforis_whisp/local_stats.py`)
- Output formatting → Output schemas: uses schemas (evidence: `src/openforis_whisp/reformat.py`)
- Risk assessment → Output formatting: formats columns (evidence: `src/openforis_whisp/risk.py`)
- Risk assessment → Earth Engine layers: checks layer names (evidence: `src/openforis_whisp/risk.py`)
- Statistics API → Runtime configuration: reads settings (evidence: `src/openforis_whisp/stats.py`)
- Earth Engine layers → Runtime configuration: reads settings (evidence: `src/openforis_whisp/datasets.py`)
- Batched statistics → Admin lookup: joins admin codes (evidence: `src/openforis_whisp/advanced_stats.py`)
- Batched statistics → Logging: logs progress (evidence: `src/openforis_whisp/advanced_stats.py`)
- Local statistics → Exception policy: preserves exceptions (evidence: `src/openforis_whisp/local_stats.py`)
- Statistics API → Exception policy: preserves exceptions (evidence: `src/openforis_whisp/stats.py`)
- Package user → Asset registry: manages assets
- Statistics API → Risk assessment: assesses risk
