# einggraumfw/era5-site-explorer architecture

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

- Interactive diagram: https://gitdiagram.com/einggraumfw/era5-site-explorer
- Repository: https://github.com/einggraumfw/era5-site-explorer

## Overview

ERA5 Site Explorer is a local web app for requesting Copernicus ERA5 wave data and analysing wave-energy resources. The principal flow is site selection and request submission, CDS download, per-node analysis, then browser results and optional screening, device, long-term, cross-check and export tools. The README documents these capabilities; some plugin and frontend wiring is represented at the subsystem level because not all implementation excerpts were provided.

Main entry points: [`app.py`](https://github.com/einggraumfw/era5-site-explorer/blob/main/app.py) (Flask app and jobs), [`plugins.py`](https://github.com/einggraumfw/era5-site-explorer/blob/main/plugins.py) (Plugin runtime), [`static/app.js`](https://github.com/einggraumfw/era5-site-explorer/blob/main/static/app.js) (Explorer UI), [`fetch_era5_waves.py`](https://github.com/einggraumfw/era5-site-explorer/blob/main/fetch_era5_waves.py) (ERA5 fetcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Web interface"]
  node_browser["Explorer UI<br/>[app.js]"]
  node_page["App page<br/>[index.html]"]
  node_server["Flask app and jobs<br/>[app.py]"]
end

subgraph group_ingestion["Data acquisition"]
  node_fetcher["ERA5 fetcher"]
  node_jobfiles[("Downloaded job data")]
end

subgraph group_analysis["Wave analysis"]
  node_analysis["Node analysis<br/>[analysis.py]"]
  node_physics["Wave calculations<br/>[wavecalc.py]"]
  node_crosscheck["Route cross-check<br/>[crosscheck.py]"]
end

subgraph group_tools["Resource tools"]
  node_screening_plugin["Screening routes"]
  node_screening["Node screening<br/>[screening.py]"]
  node_device_plugin["Device routes<br/>[plugin_device.py]"]
  node_catalogue["Device catalogue"]
  node_device["Device assessment<br/>[device.py]"]
  node_longterm_plugin["Long-term routes<br/>[plugin_longterm.py]"]
  node_longterm["Long-term statistics<br/>[longterm.py]"]
  node_export_plugin["Export routes<br/>[plugin_export.py]"]
  node_report["Reports and tables<br/>[report.py]"]
end

subgraph group_internals["Shared runtime"]
  node_plugin_runtime["Plugin runtime<br/>[plugins.py]"]
  node_safety["NetCDF and writes<br/>[netcdf_safety.py]"]
end

node_user(("Site analyst"))
node_cds["Copernicus CDS"]

node_user -->|"chooses site"| node_browser
node_page -.->|"hosts interface"| node_browser
node_browser -.->|"submits requests"| node_server
node_server -->|"starts download"| node_fetcher
node_fetcher -->|"requests ERA5"| node_cds
node_fetcher -.->|"writes downloads"| node_jobfiles
node_server -.->|"reads job data"| node_jobfiles
node_server -->|"analyses job"| node_analysis
node_analysis -->|"calculates wave metrics"| node_physics
node_analysis -->|"uses NetCDF lock"| node_safety
node_server -->|"runs comparison"| node_crosscheck
node_server -->|"loads feature routes"| node_plugin_runtime
node_plugin_runtime -->|"registers routes"| node_screening_plugin
node_plugin_runtime -->|"registers routes"| node_device_plugin
node_plugin_runtime -->|"registers routes"| node_longterm_plugin
node_plugin_runtime -->|"registers routes"| node_export_plugin
node_screening_plugin -->|"computes screening"| node_screening
node_device_plugin -->|"loads device choices"| node_catalogue
node_device_plugin -->|"assesses performance"| node_device
node_longterm_plugin -->|"computes statistics"| node_longterm
node_export_plugin -->|"builds exports"| node_report
node_plugin_runtime -->|"writes atomically"| node_safety
node_server -.->|"returns results"| node_browser

click node_browser "https://github.com/einggraumfw/era5-site-explorer/blob/main/static/app.js"
click node_page "https://github.com/einggraumfw/era5-site-explorer/blob/main/templates/index.html"
click node_server "https://github.com/einggraumfw/era5-site-explorer/blob/main/app.py"
click node_fetcher "https://github.com/einggraumfw/era5-site-explorer/blob/main/fetch_era5_waves.py"
click node_analysis "https://github.com/einggraumfw/era5-site-explorer/blob/main/analysis.py"
click node_physics "https://github.com/einggraumfw/era5-site-explorer/blob/main/wavecalc.py"
click node_crosscheck "https://github.com/einggraumfw/era5-site-explorer/blob/main/crosscheck.py"
click node_screening_plugin "https://github.com/einggraumfw/era5-site-explorer/blob/main/plugin_screening.py"
click node_screening "https://github.com/einggraumfw/era5-site-explorer/blob/main/screening.py"
click node_device_plugin "https://github.com/einggraumfw/era5-site-explorer/blob/main/plugin_device.py"
click node_catalogue "https://github.com/einggraumfw/era5-site-explorer/blob/main/devices_catalogue.py"
click node_device "https://github.com/einggraumfw/era5-site-explorer/blob/main/device.py"
click node_longterm_plugin "https://github.com/einggraumfw/era5-site-explorer/blob/main/plugin_longterm.py"
click node_longterm "https://github.com/einggraumfw/era5-site-explorer/blob/main/longterm.py"
click node_export_plugin "https://github.com/einggraumfw/era5-site-explorer/blob/main/plugin_export.py"
click node_report "https://github.com/einggraumfw/era5-site-explorer/blob/main/report.py"
click node_plugin_runtime "https://github.com/einggraumfw/era5-site-explorer/blob/main/plugins.py"
click node_safety "https://github.com/einggraumfw/era5-site-explorer/blob/main/netcdf_safety.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_browser,node_page,node_server toneBlue
class node_fetcher,node_jobfiles toneAmber
class node_analysis,node_physics,node_crosscheck toneMint
class node_screening_plugin,node_screening,node_device_plugin,node_catalogue,node_device,node_longterm_plugin,node_longterm,node_export_plugin,node_report toneRose
class node_plugin_runtime,node_safety,node_user,node_cds toneIndigo
```

## Components

### Web interface

- [Explorer UI](https://github.com/einggraumfw/era5-site-explorer/blob/main/static/app.js): `static/app.js`
- [App page](https://github.com/einggraumfw/era5-site-explorer/blob/main/templates/index.html): `templates/index.html`
- [Flask app and jobs](https://github.com/einggraumfw/era5-site-explorer/blob/main/app.py): `app.py`

### Data acquisition

- [ERA5 fetcher](https://github.com/einggraumfw/era5-site-explorer/blob/main/fetch_era5_waves.py): `fetch_era5_waves.py`
- **Downloaded job data**

### Wave analysis

- [Node analysis](https://github.com/einggraumfw/era5-site-explorer/blob/main/analysis.py): `analysis.py`
- [Wave calculations](https://github.com/einggraumfw/era5-site-explorer/blob/main/wavecalc.py): `wavecalc.py`
- [Route cross-check](https://github.com/einggraumfw/era5-site-explorer/blob/main/crosscheck.py): `crosscheck.py`

### Resource tools

- [Screening routes](https://github.com/einggraumfw/era5-site-explorer/blob/main/plugin_screening.py): `plugin_screening.py`
- [Node screening](https://github.com/einggraumfw/era5-site-explorer/blob/main/screening.py): `screening.py`
- [Device routes](https://github.com/einggraumfw/era5-site-explorer/blob/main/plugin_device.py): `plugin_device.py`
- [Device catalogue](https://github.com/einggraumfw/era5-site-explorer/blob/main/devices_catalogue.py): `devices_catalogue.py`
- [Device assessment](https://github.com/einggraumfw/era5-site-explorer/blob/main/device.py): `device.py`
- [Long-term routes](https://github.com/einggraumfw/era5-site-explorer/blob/main/plugin_longterm.py): `plugin_longterm.py`
- [Long-term statistics](https://github.com/einggraumfw/era5-site-explorer/blob/main/longterm.py): `longterm.py`
- [Export routes](https://github.com/einggraumfw/era5-site-explorer/blob/main/plugin_export.py): `plugin_export.py`
- [Reports and tables](https://github.com/einggraumfw/era5-site-explorer/blob/main/report.py): `report.py`

### Shared runtime

- [Plugin runtime](https://github.com/einggraumfw/era5-site-explorer/blob/main/plugins.py): `plugins.py`
- [NetCDF and writes](https://github.com/einggraumfw/era5-site-explorer/blob/main/netcdf_safety.py): `netcdf_safety.py`

### Other components

- **Site analyst**
- **Copernicus CDS**

## Connections

- Site analyst → Explorer UI: chooses site (evidence: `README.md`)
- App page → Explorer UI: hosts interface
- Explorer UI → Flask app and jobs: submits requests
- Flask app and jobs → ERA5 fetcher: starts download (evidence: `app.py`)
- ERA5 fetcher → Copernicus CDS: requests ERA5 (evidence: `README.md`)
- ERA5 fetcher → Downloaded job data: writes downloads
- Flask app and jobs → Downloaded job data: reads job data
- Flask app and jobs → Node analysis: analyses job (evidence: `app.py`)
- Node analysis → Wave calculations: calculates wave metrics (evidence: `analysis.py`)
- Node analysis → NetCDF and writes: uses NetCDF lock (evidence: `analysis.py`)
- Flask app and jobs → Route cross-check: runs comparison (evidence: `app.py`)
- Flask app and jobs → Plugin runtime: loads feature routes (evidence: `app.py`)
- Plugin runtime → Screening routes: registers routes (evidence: `plugins.py`)
- Plugin runtime → Device routes: registers routes (evidence: `plugins.py`)
- Plugin runtime → Long-term routes: registers routes (evidence: `plugins.py`)
- Plugin runtime → Export routes: registers routes (evidence: `plugins.py`)
- Screening routes → Node screening: computes screening (evidence: `plugin_screening.py`)
- Device routes → Device catalogue: loads device choices (evidence: `plugin_device.py`)
- Device routes → Device assessment: assesses performance (evidence: `plugin_device.py`)
- Long-term routes → Long-term statistics: computes statistics (evidence: `plugin_longterm.py`)
- Export routes → Reports and tables: builds exports (evidence: `plugin_export.py`)
- Plugin runtime → NetCDF and writes: writes atomically (evidence: `plugins.py`)
- Flask app and jobs → Explorer UI: returns results
