Add monorepo scaffolding and project documentation
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>
This commit is contained in:
Claude Opus 5
@@ -0,0 +1,131 @@
|
||||
# Architecture
|
||||
|
||||
## Shape of the system
|
||||
|
||||
```
|
||||
DPC radar API ──┐
|
||||
│ (worker only: origin header, presigned S3, 5-min cadence)
|
||||
ARPA CAP feed ──┤
|
||||
▼
|
||||
Python worker ──► object storage / CDN
|
||||
(crop, reproject, manifest.json
|
||||
colourise, render) frames/*.png
|
||||
alerts.json
|
||||
cells.json
|
||||
│
|
||||
▼
|
||||
Flutter app ◄── api.met.no (direct, identifying User-Agent)
|
||||
```
|
||||
|
||||
**The app never talks to DPC or ARPA directly.** Both would be rate-limited by
|
||||
thousands of clients, DPC presigned URLs expire in minutes, and the rasters are
|
||||
whole-Italy GeoTIFFs that a phone should not decode. The worker is the only client of
|
||||
those services, and it fans out through a CDN.
|
||||
|
||||
MET Norway is the exception: it is designed for per-client access, its license permits
|
||||
it, and forecasts are per-location so a shared cache would not help.
|
||||
|
||||
## Monorepo
|
||||
|
||||
```
|
||||
Nuvolari/
|
||||
├─ app/ Flutter application (Dart package "nuvolari")
|
||||
├─ backend/ Python worker
|
||||
├─ docs/ this documentation
|
||||
└─ tool/ verification scripts
|
||||
```
|
||||
|
||||
## App layers
|
||||
|
||||
```
|
||||
lib/
|
||||
├─ core/ cross-cutting, no feature knowledge
|
||||
│ ├─ config/ Env (dart-define), feature flags
|
||||
│ ├─ region/ RegionConfig + asset loader
|
||||
│ ├─ net/ Dio client, User-Agent and retry interceptors
|
||||
│ ├─ cache/ FrameCache (disk + memory LRU)
|
||||
│ └─ l10n/ localisation plumbing
|
||||
├─ data/ one folder per domain, each exposing an interface
|
||||
│ ├─ radar/ RadarSource + Dpc/Arpa/Mock implementations + models
|
||||
│ ├─ forecast/ ForecastSource + MetNo/IconIt2 implementations
|
||||
│ └─ alerts/ AlertSource + ArpaCap implementation
|
||||
├─ features/ one folder per screen or coherent UI area
|
||||
│ ├─ map/ timeline/ forecast/ alerts/ sources/ consent/ ads/
|
||||
└─ l10n/ app_it.arb (template)
|
||||
```
|
||||
|
||||
Dependencies point inwards: `features` depends on `data`, `data` depends on `core`,
|
||||
`core` depends on nothing in the app. A feature never imports another feature.
|
||||
|
||||
## The adapter seam
|
||||
|
||||
```dart
|
||||
abstract interface class RadarSource {
|
||||
Future<RadarManifest> getLatestManifest();
|
||||
Future<List<RadarFrame>> getFrames();
|
||||
}
|
||||
```
|
||||
|
||||
Three implementations:
|
||||
|
||||
| Implementation | Status | Purpose |
|
||||
|---|---|---|
|
||||
| `MockRadarSource` | active | Synthetic frames from assets. Runs with no network and no credentials — the default in tests and in demo mode. |
|
||||
| `DpcRadarSource` | active | Reads `manifest.json` and PNG frames from our CDN. |
|
||||
| `ArpaRadarSource` | **disabled stub** | Placeholder until ARPA authorization exists. Throws if constructed while its feature flag is off. |
|
||||
|
||||
The active source is resolved from the region config plus a runtime flag, so switching
|
||||
sources is configuration, never a code change. `ForecastSource` and `AlertSource`
|
||||
follow the same pattern.
|
||||
|
||||
Because `MockRadarSource` is a first-class implementation rather than test scaffolding,
|
||||
the whole UI — timeline, scrubbing, prefetch, cache eviction, degraded states — is
|
||||
exercisable offline.
|
||||
|
||||
## Data contract
|
||||
|
||||
`manifest.json`, published by the worker and consumed by the app:
|
||||
|
||||
```json
|
||||
{
|
||||
"region": "piemonte",
|
||||
"product": "VMI",
|
||||
"generatedAt": 1758706260000,
|
||||
"bbox": [6.55, 43.95, 9.30, 46.55],
|
||||
"crs": "EPSG:3857",
|
||||
"frames": [
|
||||
{ "ts": 1758706200000, "url": "frames/VMI/1758706200000.png" }
|
||||
],
|
||||
"legend": {
|
||||
"unit": "dBZ",
|
||||
"stops": [{ "value": 5, "color": "#4FA3D1" }]
|
||||
},
|
||||
"attribution": "Radar-DPC — CC BY-SA"
|
||||
}
|
||||
```
|
||||
|
||||
Frame URLs are relative to the manifest so the whole tree can be moved between hosts.
|
||||
The legend travels with the data: the app draws whatever the worker produced rather
|
||||
than hardcoding a palette that could drift from the rendering.
|
||||
|
||||
## Degradation
|
||||
|
||||
Failure is normal here — the worker can be behind, a frame can be missing, the phone
|
||||
can be offline. The rules:
|
||||
|
||||
- Manifest unreachable → keep the last good manifest from cache, show a
|
||||
"dati non disponibili" banner with the age of the newest frame.
|
||||
- Individual frame missing → hold the previous frame in the timeline; never a blank map.
|
||||
- No frames at all → the map and the forecast still work; only the radar layer is empty.
|
||||
- Animation stops when the app leaves the foreground (`AppLifecycleState`) so a
|
||||
backgrounded app never burns battery prefetching.
|
||||
|
||||
The banner always states **when** the data is from. Stale radar shown as if current is
|
||||
worse than no radar.
|
||||
|
||||
## Privacy by construction
|
||||
|
||||
No user location ever reaches a server. Forecast requests go from the device straight
|
||||
to MET Norway. Rain notifications work by the device subscribing to FCM topics named
|
||||
after geographic cells — the subscription happens on the device, so the backend holds
|
||||
no user records at all.
|
||||
Reference in New Issue
Block a user