Alby96andClaude Opus 5
3fcbb9f1c4
Sets up the Nuvolari monorepo layout (app/, backend/, docs/, tool/) with the groundwork that does not depend on the Flutter toolchain: gitignore covering Flutter, Python and every secret file shape; env.example.json as the template for --dart-define-from-file; a verification script that skips stages whose target does not exist yet so it is runnable from day one; and a CI workflow in GitHub Actions syntax so it runs unchanged on Gitea or GitHub. The documentation records facts verified against the live services rather than restated from the brief. Two of them change the design: - DPC VMI rasters are 1200x1400 Float32 on a 1 km grid in a custom projection centred on Italy, not EPSG:4326 or EPSG:3857, and their GeoKeys are internally inconsistent. Reprojection is mandatory and the source CRS must be read from each file rather than hardcoded. - The ARPA CAP feed carries six level values, not four: BIANCO for the avalanche scale out of season and "-" for no data. Collapsing either into VERDE would report "no alert" where the bulletin reports "not assessed". Also documents why the frames we publish inherit CC BY-SA from the DPC source, and why rain notifications subscribe to cell topics from the device so no user location ever reaches a server. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
242 lines
9.5 KiB
Markdown
242 lines
9.5 KiB
Markdown
# Data sources
|
||
|
||
Every endpoint below was verified on 2026-09-10. Anything not verified is marked
|
||
**TO VERIFY** and must not be relied on until checked.
|
||
|
||
## 1. Radar — Radar-DPC (default for the MVP)
|
||
|
||
Public platform of the Italian Dipartimento della Protezione Civile.
|
||
|
||
- Base URL: `https://radar-api.protezionecivile.it/`
|
||
- Transitional test base URL: `https://wagiqofvnk.execute-api.eu-south-1.amazonaws.com/prod`
|
||
|
||
### `GET /findLastProductByType?type=<PRODUCT>`
|
||
|
||
Returns the timestamp of the most recent sample of a product.
|
||
|
||
```json
|
||
{
|
||
"total": 1,
|
||
"lastProducts": [
|
||
{ "productType": "VMI", "time": 1758706200000, "period": "PT5M" }
|
||
]
|
||
}
|
||
```
|
||
|
||
- `time` is epoch milliseconds, UTC.
|
||
- `period` is the ISO-8601 cadence of the product.
|
||
- `400` when `type` is missing, `404` when no product is available.
|
||
|
||
### `POST /downloadProduct`
|
||
|
||
Returns a pre-signed S3 URL for the raw raster file.
|
||
|
||
```json
|
||
{ "productType": "VMI", "productDate": 1758706200000 }
|
||
```
|
||
|
||
```json
|
||
{
|
||
"bucket": "dpc-radar",
|
||
"key": "VMI/22-09-2025-14-20.tif",
|
||
"url": "https://dpc-radar.s3.eu-south-1.amazonaws.com/...",
|
||
"expiresSeconds": 900
|
||
}
|
||
```
|
||
|
||
- `productDate` must be **rounded down to the product step**, otherwise `404`.
|
||
- Pre-signed URLs expire after 300–900 s: download immediately, never cache the URL.
|
||
- `400` when `productDate` is missing or non-numeric.
|
||
|
||
### Mandatory header
|
||
|
||
```
|
||
origin: https://radar.protezionecivile.it
|
||
```
|
||
|
||
Required on **every** request to the platform for security reasons; requests without it
|
||
are rejected. `Content-Type: application/json` is also required on `downloadProduct`.
|
||
|
||
### Products and cadence
|
||
|
||
| Cadence | Products |
|
||
|---|---|
|
||
| 5 min | `VMI`, `SRI`, `SRT1`, `IR_108` |
|
||
| 30–60 min | `TEMP`, `CUM3`, `CUM6`, `CUM12`, `CUM24`, `CAPPI_1`…`CAPPI_10`, `VIL`, `ETM`, `POH` |
|
||
| — | `SITES` (GeoJSON, fetched directly from S3 with `GET`) |
|
||
|
||
The MVP uses **`VMI`** (Vertical Maximum Intensity) as the precipitation layer.
|
||
History retention is 14 days. Files are GeoTIFF; CRS is read from the file metadata
|
||
rather than assumed — the worker reprojects to EPSG:3857 in all cases.
|
||
|
||
### Raster format (read from a live VMI file, 2026-09-10)
|
||
|
||
| Property | Value |
|
||
|---|---|
|
||
| Size | 1200 × 1400 px |
|
||
| Pixel size | 1000 × 1000 m — a **1 km grid** |
|
||
| Bands / type | 1 band, **Float32**, LZW compressed |
|
||
| Tie point | raster (0,0) → model (-600000, 650000) |
|
||
| Model type | **projected**, datum WGS84 (GeographicTypeGeoKey 4326) |
|
||
| Projection centre | 12.5° E, 42.0° N (`ProjCenterLong`/`ProjCenterLat`) |
|
||
| Linear units | metre |
|
||
| Nodata tag | absent — expect NaN |
|
||
|
||
**The rasters are not in EPSG:4326 and not in EPSG:3857.** They are on a custom
|
||
projection centred on Italy, so reprojection to Web Mercator is mandatory, not an
|
||
optimisation. The extent works out to 1200 km east-west and 1400 km north-south around
|
||
that centre, which covers the whole country — the worker crops to the region bounding
|
||
box before doing anything else, so it never carries the full mosaic through the
|
||
pipeline.
|
||
|
||
The GeoKeys as written are internally inconsistent (`ProjCoordTransGeoKey` = 1, which
|
||
is transverse Mercator, combined with the centre keys an azimuthal projection uses).
|
||
**Do not hardcode a source CRS.** The worker reads the CRS from the file with rasterio
|
||
and warps from whatever it finds, and logs the detected CRS on every run so a change at
|
||
the source is visible instead of silently shifting the imagery.
|
||
|
||
Values are physical units (dBZ for VMI), not palette indices — the colour mapping is
|
||
ours, and the legend that goes with it is published in the manifest.
|
||
|
||
### Push channel
|
||
|
||
`wss://radar-wss.protezionecivile.it` pushes a notification whenever a new sample is
|
||
published. The worker uses this as its **primary trigger**, with a 5-minute cron as a
|
||
fallback, so we never poll DPC aggressively.
|
||
|
||
### License
|
||
|
||
**CC BY-SA.** Attribution to "Radar-DPC" is mandatory and derived products must be
|
||
released under the same license. The rendered PNG frames we publish are a derived
|
||
product and inherit CC BY-SA.
|
||
|
||
Docs: <https://dpc-radar.readthedocs.io/it/latest/>
|
||
|
||
## 2. Radar — ARPA Piemonte (future adapter, disabled)
|
||
|
||
C-band polarimetric radars at Bric della Croce and Monte Settepani, HDF5 ODIM every
|
||
5 minutes. Access requires authorization requested at `info.meteo@arpa.piemonte.it`.
|
||
|
||
License CC BY 4.0, attribution "Fonte: Arpa Piemonte - www.arpa.piemonte.it".
|
||
|
||
`ArpaRadarSource` exists as a **disabled stub**. No request for authorization has been
|
||
sent and none will be sent without an explicit instruction from the project owner.
|
||
|
||
## 3. Forecast — MET Norway
|
||
|
||
- `https://api.met.no/weatherapi/locationforecast/2.0/compact?lat=<lat>&lon=<lon>`
|
||
- A **descriptive, identifying `User-Agent` is mandatory** (application name plus a
|
||
contact address). Requests with a generic or missing User-Agent are blocked.
|
||
- Honour `Expires` and use `If-Modified-Since`; do not re-request before expiry.
|
||
- License CC BY 4.0, **commercial use allowed**.
|
||
|
||
### Fallback — ItaliaMeteo ICON-2I via MeteoHub
|
||
|
||
License CC BY 4.0, attribution "ItaliaMeteo-ARPAE". Endpoint details **TO VERIFY**
|
||
before the adapter is enabled.
|
||
|
||
### Explicitly excluded
|
||
|
||
**Open-Meteo free tier** — non-commercial only, and this app carries ads.
|
||
|
||
## 4. Alerts — ARPA Piemonte XML-CAP
|
||
|
||
- Feed: `https://www.arpa.piemonte.it/export/xmlcap/allerta.xml`
|
||
- Landing page: <https://www.arpa.piemonte.it/rischi_naturali/snippets_arpa/allerta/index.html>
|
||
- Official PDF bulletin: `https://www.arpa.piemonte.it/rischi_naturali/boll/bollettino_allerta.pdf`
|
||
|
||
Issued daily by 13:00 by the Centro Funzionale Regionale, 36 hours of validity.
|
||
|
||
### Alert zones (11)
|
||
|
||
`Piem-A` … `Piem-M` (A, B, C, D, E, F, G, H, I, L, M), covering: Toce; Val Sesia/Cervo/
|
||
Chiusella; Valli Orco/Lanzo/bassa val Susa/Sangone; Alta val Susa/Chisone/Pellice/Po;
|
||
Valli Varaita/Maira/Stura; Valle Tanaro; Belbo e Bormida; Scrivia; Pianura
|
||
settentrionale; Pianura e colline torinesi; Pianura cuneese.
|
||
The exact code-to-name mapping is stored in `app/assets/regions/piemonte.json`.
|
||
|
||
### CAP document structure (verified against the live feed, 2026-09-10)
|
||
|
||
One `<alert>` contains one `<info>` block **per zone**; the zone is in
|
||
`info/area/areaDesc` and holds the bare code (`Piem-A`), not a name.
|
||
|
||
```xml
|
||
<alert xmlns="urn:oasis:names:tc:emergency:cap:1.2">
|
||
<identifier>261/2026</identifier> <!-- bulletin number / year -->
|
||
<sender>centro.funzionale@arpa.piemonte.it</sender>
|
||
<sent>2026-09-09T10:00:02+00:00</sent>
|
||
<status>Actual</status><msgType>Alert</msgType><scope>Public</scope>
|
||
<note>AVVISO DI CONDIZIONI METEOROLOGICHE AVVERSE ...</note>
|
||
<info>
|
||
<event>GIALLO</event> <!-- overall level for this zone -->
|
||
<onset>...</onset><expires>...</expires>
|
||
<parameter><valueName>EFFETTI SUL TERRITORIO</valueName><value>...</value></parameter>
|
||
<parameter><valueName>TEMPORALI_1224</valueName><value>GIALLO</value></parameter>
|
||
<parameter><valueName>TEMPORALI_2436</valueName><value>VERDE</value></parameter>
|
||
...
|
||
<area><areaDesc>Piem-A</areaDesc></area>
|
||
</info>
|
||
<!-- 10 more info blocks, one per zone -->
|
||
</alert>
|
||
```
|
||
|
||
Parameters are named `<CATEGORY>_<WINDOW>`:
|
||
|
||
- **Categories** — `IDRAULICO`, `IDROGEOLOGICO`, `TEMPORALI`, `NEVE`, `VALANGHE`.
|
||
- **Windows** — `1224` (hours 12–24) and `2436` (hours 24–36), matching the 36 hours
|
||
of validity.
|
||
|
||
So each zone carries 10 level values plus one overall `<event>` level and a free-text
|
||
`EFFETTI SUL TERRITORIO`.
|
||
|
||
### Levels — six values, not four
|
||
|
||
| Value | Meaning |
|
||
|---|---|
|
||
| `VERDE` | no significant phenomena |
|
||
| `GIALLO` | localised phenomena |
|
||
| `ARANCIONE` | widespread phenomena |
|
||
| `ROSSO` | numerous or extensive phenomena |
|
||
| `BIANCO` | **avalanche scale only** — outside the season / not assessed |
|
||
| `-` | no value published for that category and window |
|
||
|
||
`BIANCO` and `-` are not "green with a different name" and must not be collapsed into
|
||
it. The parser models the level as an enum with explicit `bianco` and `notAvailable`
|
||
members, and the UI renders them as their own state rather than as "no alert".
|
||
|
||
Levels are republished **verbatim, never reinterpreted**, always alongside a link to
|
||
the official bulletin. No license is stated on the ARPA page, so we credit ARPA
|
||
Piemonte and link the source rather than claiming any reuse right.
|
||
|
||
Official bulletin PDF, linked from every alert view:
|
||
`https://www.arpa.piemonte.it/rischi_naturali/boll/bollettino_allerta.pdf`
|
||
|
||
### Zone codes
|
||
|
||
`Piem-A` … `Piem-M`, eleven zones: **the Italian alphabet is used, so J and K do not
|
||
exist** — the sequence is A B C D E F G H I L M. The code-to-name mapping lives in
|
||
`app/assets/regions/piemonte.json`; the human-readable names are not in the feed and
|
||
come from the ARPA zone documentation.
|
||
|
||
A captured copy of the live feed is kept as a test fixture so the parser is verified
|
||
against the real document rather than a hand-written approximation.
|
||
|
||
## 5. Municipalities — ISTAT
|
||
|
||
Piedmont municipality list to bundle in assets. Source **TO VERIFY** — the ISTAT
|
||
"Codici statistici delle unità amministrative territoriali" dataset is the intended
|
||
origin but the stable download URL has not been confirmed yet.
|
||
|
||
## 6. Base map — OpenStreetMap
|
||
|
||
Vector tiles via MapTiler (API key required, supplied through `MAP_STYLE_URL`) or
|
||
self-hosted PMTiles. **OSM/ODbL attribution must stay visible on the map at all times.**
|
||
|
||
Until a key is configured the app falls back to a minimal local style so that
|
||
development and tests run fully offline.
|
||
|
||
## 7. Lightning — excluded
|
||
|
||
**Blitzortung must not be used**: its data prohibits commercial use. If a lightning
|
||
layer is ever added it will come from the DPC `LTG` product instead.
|