# baptistefeldmann/observatoire-secheresse architecture

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

- Interactive diagram: https://gitdiagram.com/baptistefeldmann/observatoire-secheresse
- Repository: https://github.com/baptistefeldmann/observatoire-secheresse

## Overview

This repository implements a configurable, weekly departmental drought observatory. Its main workflow builds geographic and station reference data, ingests hydrological, groundwater, ONDE, reservoir, and weather observations, derives reference normals and weekly indices, then persists results for downstream use, including PostGIS loading. The graph reflects documented and indexed module relationships; API and dashboard are explicitly future work, and Sentinel-2 is described as a later capability, without a sampled implementation to connect.

Main entry points: [`pipeline/referentiels.py`](https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/referentiels.py) (Reference builder), [`pipeline/__main__.py`](https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/__main__.py) (Pipeline CLI), [`pipeline/ingestion.py`](https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/ingestion.py) (Observation ingestion), [`pipeline/indices/__init__.py`](https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/indices/__init__.py) (Weekly indices)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Configuration"]
  node_cli["Pipeline CLI<br/>[__main__.py]"]
  node_config["Config validation<br/>[config.py]"]
end

subgraph group_acquisition["Data acquisition"]
  node_http["HTTP client<br/>[http.py]"]
  node_refbuild["Reference builder<br/>[referentiels.py]"]
  node_zonage["Zones and station links<br/>[zonage.py]"]
  node_sandre["SANDRE data<br/>[sandre.py]"]
  node_communes["Commune data<br/>[communes.py]"]
  node_meteo["Weather and SIM<br/>[meteo.py]"]
  node_station_sources["Hydro and ONDE stations<br/>[hydro.py]"]
  node_groundwater["Groundwater stations<br/>[piezo.py]"]
  node_reservoirs["Reservoir sources<br/>[retenues.py]"]
  node_ingestion["Observation ingestion<br/>[ingestion.py]"]
  node_hubeau["Hub’Eau helpers<br/>[hubeau.py]"]
end

subgraph group_analytics["Drought analytics"]
  node_normals["Reference normals"]
  node_normal_common["Normal helpers<br/>[commun.py]"]
  node_debit_normal["Flow normals<br/>[debit.py]"]
  node_spi_normal["SPI normals<br/>[spi.py]"]
  node_indices["Weekly indices<br/>[__init__.py]"]
  node_index_common["Index utilities<br/>[commun.py]"]
  node_index_components["Index components"]
end

subgraph group_persistence["Storage and access"]
  node_parquet["Parquet storage<br/>[stockage.py]"]
  node_schema["Data schemas<br/>[schema.py]"]
  node_rawdata[("Raw observations")]
  node_indexdata[("Index outputs")]
  node_db_load["PostGIS loader<br/>[chargement.py]"]
  node_postgis[("PostGIS database")]
end

node_operator(("Operator"))

node_operator -->|"runs"| node_cli
node_cli -->|"loads"| node_config
node_cli -->|"builds references"| node_refbuild
node_cli -->|"runs ingestion"| node_ingestion
node_cli -->|"builds normals"| node_normals
node_cli -->|"calculates indices"| node_indices
node_cli -->|"loads database"| node_db_load
node_refbuild -->|"fetches"| node_communes
node_refbuild -->|"fetches"| node_sandre
node_refbuild -->|"fetches"| node_meteo
node_refbuild -->|"fetches"| node_station_sources
node_refbuild -->|"fetches"| node_groundwater
node_refbuild -->|"fetches"| node_reservoirs
node_refbuild -->|"constructs zones"| node_zonage
node_refbuild -->|"writes references"| node_parquet
node_ingestion -->|"reads references"| node_refbuild
node_ingestion -->|"ingests observations"| node_groundwater
node_ingestion -->|"ingests observations"| node_station_sources
node_ingestion -->|"ingests observations"| node_meteo
node_ingestion -->|"ingests observations"| node_reservoirs
node_ingestion -->|"stores observations"| node_parquet
node_groundwater -->|"uses helpers"| node_hubeau
node_station_sources -->|"uses helpers"| node_hubeau
node_groundwater -->|"requests data"| node_http
node_station_sources -->|"requests data"| node_http
node_meteo -->|"requests data"| node_http
node_reservoirs -->|"requests data"| node_http
node_communes -->|"requests data"| node_http
node_sandre -->|"requests data"| node_http
node_normals -->|"uses helpers"| node_normal_common
node_debit_normal -->|"uses helpers"| node_normal_common
node_spi_normal -->|"uses helpers"| node_normal_common
node_normals -->|"reads raw data"| node_parquet
node_indices -->|"uses utilities"| node_index_common
node_indices -->|"dispatches calculations"| node_index_components
node_indices -->|"reads normals"| node_normals
node_indices -->|"reads observations"| node_parquet
node_indices -->|"normalizes outputs"| node_schema
node_indices -->|"writes indices"| node_parquet
node_parquet -->|"persists observations"| node_rawdata
node_parquet -->|"persists indices"| node_indexdata
node_db_load -->|"loads tables"| node_postgis

click node_cli "https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/__main__.py"
click node_config "https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/config.py"
click node_http "https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/http.py"
click node_refbuild "https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/referentiels.py"
click node_zonage "https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/zonage.py"
click node_sandre "https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/sources/sandre.py"
click node_communes "https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/sources/communes.py"
click node_meteo "https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/sources/meteo.py"
click node_station_sources "https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/sources/hydro.py"
click node_groundwater "https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/sources/piezo.py"
click node_reservoirs "https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/sources/retenues.py"
click node_ingestion "https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/ingestion.py"
click node_hubeau "https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/sources/hubeau.py"
click node_parquet "https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/stockage.py"
click node_schema "https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/schema.py"
click node_rawdata "https://github.com/baptistefeldmann/observatoire-secheresse/tree/main/data"
click node_normals "https://github.com/baptistefeldmann/observatoire-secheresse/tree/main/pipeline/reference"
click node_normal_common "https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/reference/commun.py"
click node_debit_normal "https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/reference/debit.py"
click node_spi_normal "https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/reference/spi.py"
click node_indices "https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/indices/__init__.py"
click node_index_common "https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/indices/commun.py"
click node_index_components "https://github.com/baptistefeldmann/observatoire-secheresse/tree/main/pipeline/indices"
click node_indexdata "https://github.com/baptistefeldmann/observatoire-secheresse/tree/main/data"
click node_db_load "https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/db/chargement.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_cli,node_config toneBlue
class node_http,node_refbuild,node_zonage,node_sandre,node_communes,node_meteo,node_station_sources,node_groundwater,node_reservoirs,node_ingestion,node_hubeau toneAmber
class node_normals,node_normal_common,node_debit_normal,node_spi_normal,node_indices,node_index_common,node_index_components toneMint
class node_parquet,node_schema,node_rawdata,node_indexdata,node_db_load,node_postgis toneRose
class node_operator toneIndigo
```

## Components

### Configuration

- [Pipeline CLI](https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/__main__.py): `pipeline/__main__.py`
- [Config validation](https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/config.py): `pipeline/config.py`

### Data acquisition

- [HTTP client](https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/http.py): `pipeline/http.py`
- [Reference builder](https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/referentiels.py): `pipeline/referentiels.py`
- [Zones and station links](https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/zonage.py): `pipeline/zonage.py`
- [SANDRE data](https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/sources/sandre.py): `pipeline/sources/sandre.py`
- [Commune data](https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/sources/communes.py): `pipeline/sources/communes.py`
- [Weather and SIM](https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/sources/meteo.py): `pipeline/sources/meteo.py`
- [Hydro and ONDE stations](https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/sources/hydro.py): `pipeline/sources/hydro.py`
- [Groundwater stations](https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/sources/piezo.py): `pipeline/sources/piezo.py`
- [Reservoir sources](https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/sources/retenues.py): `pipeline/sources/retenues.py`
- [Observation ingestion](https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/ingestion.py): `pipeline/ingestion.py`
- [Hub’Eau helpers](https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/sources/hubeau.py): `pipeline/sources/hubeau.py`

### Drought analytics

- [Reference normals](https://github.com/baptistefeldmann/observatoire-secheresse/tree/main/pipeline/reference): `pipeline/reference`
- [Normal helpers](https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/reference/commun.py): `pipeline/reference/commun.py`
- [Flow normals](https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/reference/debit.py): `pipeline/reference/debit.py`
- [SPI normals](https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/reference/spi.py): `pipeline/reference/spi.py`
- [Weekly indices](https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/indices/__init__.py): `pipeline/indices/__init__.py`
- [Index utilities](https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/indices/commun.py): `pipeline/indices/commun.py`
- [Index components](https://github.com/baptistefeldmann/observatoire-secheresse/tree/main/pipeline/indices): `pipeline/indices`

### Storage and access

- [Parquet storage](https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/stockage.py): `pipeline/stockage.py`
- [Data schemas](https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/schema.py): `pipeline/schema.py`
- [Raw observations](https://github.com/baptistefeldmann/observatoire-secheresse/tree/main/data): `data`
- [Index outputs](https://github.com/baptistefeldmann/observatoire-secheresse/tree/main/data): `data`
- [PostGIS loader](https://github.com/baptistefeldmann/observatoire-secheresse/blob/main/pipeline/db/chargement.py): `pipeline/db/chargement.py`
- **PostGIS database**

### Other components

- **Operator**

## Connections

- Operator → Pipeline CLI: runs (evidence: `README.md`)
- Pipeline CLI → Config validation: loads (evidence: `pipeline/__main__.py`)
- Pipeline CLI → Reference builder: builds references (evidence: `pipeline/__main__.py`)
- Pipeline CLI → Observation ingestion: runs ingestion (evidence: `pipeline/__main__.py`)
- Pipeline CLI → Reference normals: builds normals (evidence: `pipeline/__main__.py`)
- Pipeline CLI → Weekly indices: calculates indices (evidence: `pipeline/__main__.py`)
- Pipeline CLI → PostGIS loader: loads database (evidence: `pipeline/__main__.py`)
- Reference builder → Commune data: fetches (evidence: `pipeline/referentiels.py`)
- Reference builder → SANDRE data: fetches (evidence: `pipeline/referentiels.py`)
- Reference builder → Weather and SIM: fetches (evidence: `pipeline/referentiels.py`)
- Reference builder → Hydro and ONDE stations: fetches (evidence: `pipeline/referentiels.py`)
- Reference builder → Groundwater stations: fetches (evidence: `pipeline/referentiels.py`)
- Reference builder → Reservoir sources: fetches (evidence: `pipeline/referentiels.py`)
- Reference builder → Zones and station links: constructs zones (evidence: `pipeline/referentiels.py`)
- Reference builder → Parquet storage: writes references (evidence: `pipeline/referentiels.py`)
- Observation ingestion → Reference builder: reads references (evidence: `pipeline/ingestion.py`)
- Observation ingestion → Groundwater stations: ingests observations (evidence: `pipeline/ingestion.py`)
- Observation ingestion → Hydro and ONDE stations: ingests observations (evidence: `pipeline/ingestion.py`)
- Observation ingestion → Weather and SIM: ingests observations (evidence: `pipeline/ingestion.py`)
- Observation ingestion → Reservoir sources: ingests observations (evidence: `pipeline/ingestion.py`)
- Observation ingestion → Parquet storage: stores observations (evidence: `pipeline/ingestion.py`)
- Groundwater stations → Hub’Eau helpers: uses helpers (evidence: `pipeline/sources/piezo.py`)
- Hydro and ONDE stations → Hub’Eau helpers: uses helpers (evidence: `pipeline/sources/hydro.py`)
- Groundwater stations → HTTP client: requests data (evidence: `pipeline/sources/piezo.py`)
- Hydro and ONDE stations → HTTP client: requests data (evidence: `pipeline/sources/hydro.py`)
- Weather and SIM → HTTP client: requests data (evidence: `pipeline/sources/meteo.py`)
- Reservoir sources → HTTP client: requests data (evidence: `pipeline/sources/retenues.py`)
- Commune data → HTTP client: requests data (evidence: `pipeline/sources/communes.py`)
- SANDRE data → HTTP client: requests data (evidence: `pipeline/sources/sandre.py`)
- Reference normals → Normal helpers: uses helpers (evidence: `pipeline/reference/__init__.py`)
- Flow normals → Normal helpers: uses helpers (evidence: `pipeline/reference/debit.py`)
- SPI normals → Normal helpers: uses helpers (evidence: `pipeline/reference/spi.py`)
- Reference normals → Parquet storage: reads raw data (evidence: `pipeline/reference/commun.py`)
- Weekly indices → Index utilities: uses utilities (evidence: `pipeline/indices/__init__.py`)
- Weekly indices → Index components: dispatches calculations (evidence: `pipeline/indices/__init__.py`)
- Weekly indices → Reference normals: reads normals (evidence: `pipeline/indices/__init__.py`)
- Weekly indices → Parquet storage: reads observations (evidence: `pipeline/indices/__init__.py`)
- Weekly indices → Data schemas: normalizes outputs (evidence: `pipeline/indices/__init__.py`)
- Weekly indices → Parquet storage: writes indices (evidence: `pipeline/indices/__init__.py`)
- Parquet storage → Raw observations: persists observations
- Parquet storage → Index outputs: persists indices
- PostGIS loader → PostGIS database: loads tables (evidence: `README.md`)
