# worldcereal/worldcereal-classification architecture

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

- Interactive diagram: https://gitdiagram.com/worldcereal/worldcereal-classification
- Repository: https://github.com/worldcereal/worldcereal-classification

## Overview

WorldCereal is a Python system for producing cropland and crop-type maps from satellite and auxiliary data, primarily through cloud openEO jobs. A user specifies an area, time range, product, and optional season or model; the job manager prepares and runs work, and retrieves outputs. The repository also supports notebook-based reference-data extraction and custom model training, alongside local inference and STAC utilities. Edges are limited to relationships documented in the README or visible in the provided source index; several feature branches are shown without guessed internal wiring.

Main entry points: [`src/worldcereal/jobmanager.py`](https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/jobmanager.py) (Batch job manager), [`src/worldcereal/job.py`](https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/job.py) (Inference job), [`notebooks/notebook_utils/classification_app.py`](https://github.com/worldcereal/worldcereal-classification/blob/main/notebooks/notebook_utils/classification_app.py) (Classification app), [`notebooks/notebook_utils/extractions.py`](https://github.com/worldcereal/worldcereal-classification/blob/main/notebooks/notebook_utils/extractions.py) (Extraction tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_jobs["Job orchestration"]
  node_params["Job parameters<br/>[job_params.py]"]
  node_task["Task types<br/>[parameters.py]"]
  node_manager["Batch job manager<br/>[jobmanager.py]"]
  node_job["Inference job<br/>[job.py]"]
end

subgraph group_processing["Mapping workflows"]
  node_workflow["Workflow presets<br/>[workflow_config.py]"]
  node_preprocess["Satellite preprocessing<br/>[preprocessing.py]"]
  node_inference["Seasonal inference<br/>[inference.py]"]
  node_catboost["CatBoost inference"]
  node_local["Local inference<br/>[local_inference.py]"]
  node_seasons["Season definitions<br/>[seasons.py]"]
end

subgraph group_training["Training and data"]
  node_training_data["Training data<br/>[data.py]"]
  node_datasets["Model datasets<br/>[datasets.py]"]
  node_seasonal_train["Seasonal training<br/>[seasonal.py]"]
end

subgraph group_notebooks["Notebook tools"]
  node_app["Classification app"]
  node_notebook_jobs["Notebook job tools<br/>[job_manager.py]"]
  node_notebook_extract["Extraction tools<br/>[extractions.py]"]
  node_auth["CDSE authentication<br/>[auth_utils.py]"]
end

subgraph group_data["Reference data and catalogues"]
  node_refdata["Reference data access<br/>[refdata.py]"]
  node_rdm["Reference Data Module<br/>[rdm_interaction.py]"]
  node_stac["STAC interaction"]
  node_legend["Class legends<br/>[legend.py]"]
  node_catalogue["STAC catalogue builder"]
end

node_user(("Map user"))
node_backend{{"openEO backend"}}
node_outputs["Downloaded results"]

node_user -->|"specifies"| node_params
node_params -->|"configures"| node_manager
node_task -->|"selects task"| node_manager
node_manager -->|"dispatches"| node_job
node_job -->|"configures"| node_workflow
node_job -->|"uses"| node_preprocess
node_job -->|"invokes"| node_inference
node_manager -->|"submits jobs"| node_backend
node_manager -->|"downloads assets"| node_outputs
node_local -->|"uses"| node_inference
node_app -->|"retrieves data"| node_notebook_extract
node_app -->|"launches jobs"| node_notebook_jobs
node_app -->|"uses login"| node_auth
node_notebook_extract -->|"queries"| node_refdata
node_notebook_extract -->|"uses API"| node_rdm
node_training_data -->|"uses"| node_datasets
node_datasets -->|"uses season logic"| node_seasonal_train
node_refdata -->|"uses labels"| node_legend
node_catalogue -.->|"builds catalogue"| node_stac
node_user -.->|"trains custom models"| node_training_data
node_manager -.->|"optional inference"| node_catboost
node_manager -->|"resolves seasons"| node_seasons

click node_params "https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/job_params.py"
click node_task "https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/parameters.py"
click node_manager "https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/jobmanager.py"
click node_job "https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/job.py"
click node_workflow "https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/openeo/workflow_config.py"
click node_preprocess "https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/openeo/preprocessing.py"
click node_inference "https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/openeo/inference.py"
click node_catboost "https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/openeo/inference_catboost.py"
click node_local "https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/local_inference.py"
click node_seasons "https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/seasons.py"
click node_app "https://github.com/worldcereal/worldcereal-classification/blob/main/notebooks/notebook_utils/classification_app.py"
click node_notebook_jobs "https://github.com/worldcereal/worldcereal-classification/blob/main/notebooks/notebook_utils/job_manager.py"
click node_notebook_extract "https://github.com/worldcereal/worldcereal-classification/blob/main/notebooks/notebook_utils/extractions.py"
click node_auth "https://github.com/worldcereal/worldcereal-classification/blob/main/notebooks/notebook_utils/auth_utils.py"
click node_training_data "https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/train/data.py"
click node_datasets "https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/train/datasets.py"
click node_seasonal_train "https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/train/seasonal.py"
click node_refdata "https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/utils/refdata.py"
click node_rdm "https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/rdm_api/rdm_interaction.py"
click node_stac "https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/stac/stac_api_interaction.py"
click node_legend "https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/utils/legend.py"
click node_catalogue "https://github.com/worldcereal/worldcereal-classification/blob/main/scripts/stac/catalogue_builder.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_params,node_task,node_manager,node_job,node_user toneBlue
class node_workflow,node_preprocess,node_inference,node_catboost,node_local,node_seasons toneAmber
class node_training_data,node_datasets,node_seasonal_train toneMint
class node_app,node_notebook_jobs,node_notebook_extract,node_auth toneRose
class node_refdata,node_rdm,node_stac,node_legend,node_catalogue,node_backend,node_outputs toneIndigo
```

## Components

### Job orchestration

- [Job parameters](https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/job_params.py): `src/worldcereal/job_params.py`
- [Task types](https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/parameters.py): `src/worldcereal/parameters.py`
- [Batch job manager](https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/jobmanager.py): `src/worldcereal/jobmanager.py`
- [Inference job](https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/job.py): `src/worldcereal/job.py`

### Mapping workflows

- [Workflow presets](https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/openeo/workflow_config.py): `src/worldcereal/openeo/workflow_config.py`
- [Satellite preprocessing](https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/openeo/preprocessing.py): `src/worldcereal/openeo/preprocessing.py`
- [Seasonal inference](https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/openeo/inference.py): `src/worldcereal/openeo/inference.py`
- [CatBoost inference](https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/openeo/inference_catboost.py): `src/worldcereal/openeo/inference_catboost.py`
- [Local inference](https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/local_inference.py): `src/worldcereal/local_inference.py`
- [Season definitions](https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/seasons.py): `src/worldcereal/seasons.py`

### Training and data

- [Training data](https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/train/data.py): `src/worldcereal/train/data.py`
- [Model datasets](https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/train/datasets.py): `src/worldcereal/train/datasets.py`
- [Seasonal training](https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/train/seasonal.py): `src/worldcereal/train/seasonal.py`

### Notebook tools

- [Classification app](https://github.com/worldcereal/worldcereal-classification/blob/main/notebooks/notebook_utils/classification_app.py): `notebooks/notebook_utils/classification_app.py`
- [Notebook job tools](https://github.com/worldcereal/worldcereal-classification/blob/main/notebooks/notebook_utils/job_manager.py): `notebooks/notebook_utils/job_manager.py`
- [Extraction tools](https://github.com/worldcereal/worldcereal-classification/blob/main/notebooks/notebook_utils/extractions.py): `notebooks/notebook_utils/extractions.py`
- [CDSE authentication](https://github.com/worldcereal/worldcereal-classification/blob/main/notebooks/notebook_utils/auth_utils.py): `notebooks/notebook_utils/auth_utils.py`

### Reference data and catalogues

- [Reference data access](https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/utils/refdata.py): `src/worldcereal/utils/refdata.py`
- [Reference Data Module](https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/rdm_api/rdm_interaction.py): `src/worldcereal/rdm_api/rdm_interaction.py`
- [STAC interaction](https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/stac/stac_api_interaction.py): `src/worldcereal/stac/stac_api_interaction.py`
- [Class legends](https://github.com/worldcereal/worldcereal-classification/blob/main/src/worldcereal/utils/legend.py): `src/worldcereal/utils/legend.py`
- [STAC catalogue builder](https://github.com/worldcereal/worldcereal-classification/blob/main/scripts/stac/catalogue_builder.py): `scripts/stac/catalogue_builder.py`

### Other components

- **Map user**
- **openEO backend**
- **Downloaded results**

## Connections

- Map user → Job parameters: specifies
- Job parameters → Batch job manager: configures (evidence: `src/worldcereal/jobmanager.py`)
- Task types → Batch job manager: selects task (evidence: `src/worldcereal/jobmanager.py`)
- Batch job manager → Inference job: dispatches (evidence: `src/worldcereal/jobmanager.py`)
- Inference job → Workflow presets: configures (evidence: `src/worldcereal/job.py`)
- Inference job → Satellite preprocessing: uses (evidence: `src/worldcereal/job.py`)
- Inference job → Seasonal inference: invokes (evidence: `src/worldcereal/job.py`)
- Batch job manager → openEO backend: submits jobs
- Batch job manager → Downloaded results: downloads assets (evidence: `src/worldcereal/jobmanager.py`)
- Local inference → Seasonal inference: uses (evidence: `src/worldcereal/local_inference.py`)
- Classification app → Extraction tools: retrieves data (evidence: `notebooks/notebook_utils/classification_app.py`)
- Classification app → Notebook job tools: launches jobs (evidence: `notebooks/notebook_utils/classification_app.py`)
- Classification app → CDSE authentication: uses login (evidence: `notebooks/notebook_utils/classification_app.py`)
- Extraction tools → Reference data access: queries (evidence: `notebooks/notebook_utils/extractions.py`)
- Extraction tools → Reference Data Module: uses API (evidence: `notebooks/notebook_utils/extractions.py`)
- Training data → Model datasets: uses (evidence: `src/worldcereal/train/data.py`)
- Model datasets → Seasonal training: uses season logic (evidence: `src/worldcereal/train/datasets.py`)
- Reference data access → Class legends: uses labels (evidence: `src/worldcereal/utils/refdata.py`)
- STAC catalogue builder → STAC interaction: builds catalogue
- Map user → Training data: trains custom models
- Batch job manager → CatBoost inference: optional inference
- Batch job manager → Season definitions: resolves seasons (evidence: `src/worldcereal/jobmanager.py`)
