Alby96andClaude Opus 5
f3a0e3794a
Drops forecasts, lightning, the home-screen widget and advertising. What remains is radar on a map, the official ARPA alert bulletin, and rain notifications. The base map is now OpenFreeMap's Positron style: real OpenStreetMap vector tiles with no API key, no registration, no request limits and commercial use permitted. Every other free tier — MapTiler, Stadia, Jawg, Thunderforest — needs a key, which is a secret to manage, a quota to outgrow and a signup to complete before anyone can build the project, and the map is the one thing the app cannot work without. Positron rather than Liberty or Bright because the radar overlay has to be the loudest thing on screen, and a desaturated grey base is built to sit under data. Its style JSON carries no `attribution` field, so MapLibre displays no credits by itself. The app renders them from the region config instead: the two mandatory credits, OpenStreetMap and OpenMapTiles, go in the always-visible bar, and OpenFreeMap's own credit — optional by their terms — is listed on the Sources screen with the rest. The bundled offline style is still reachable with MAP_STYLE_URL=offline, and still claims no base map attribution, because crediting OpenStreetMap while showing it would be a false claim. Radar-DPC stays the source. ARPA Piemonte's own radar remains a disabled stub for two reasons that belong to the project owner, not to the code: the real-time access link is only issued by email, and the open-data page states the data is "gratuiti" and nothing else. Free of charge is not a licence, and rendering those volumes into frames served from a CDN is redistribution. Both questions go in the same email. An earlier draft of the docs recorded ARPA radar as CC BY 4.0; the source page does not support that, so the claim is removed rather than carried forward. The documentation is updated throughout rather than annotated: CLAUDE.md gains an explicit scope boundary, data-sources drops MET Norway and ISTAT and gains the base map, licenses records that free of charge is not a licence, privacy loses the whole advertising section, and the roadmap is renumbered so the backend worker is next — until it exists, DpcRadarSource has nothing to read. licenses.md keeps Open-Meteo and Blitzortung listed as excluded even though the features that would have used them are gone: both are non-commercial-only, ads are a plausible future, and neither should be adopted on the grounds that there are none today. Verified: analyze clean, 130 tests passing, and on the emulator the radar overlay sits correctly over Piedmont on real OSM tiles with Turin, Milan and Genoa labelled, the age reads "Aggiornato 4 minuti fa", and the Sources screen lists all five credits with their licences. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
134 lines
5.0 KiB
Markdown
134 lines
5.0 KiB
Markdown
# 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 ──► OpenFreeMap (base map tiles)
|
|
```
|
|
|
|
**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.
|
|
|
|
The base map is the one exception, and it is not our data: OpenFreeMap serves public
|
|
OpenStreetMap vector tiles with no key and no limits, and proxying them through our own
|
|
infrastructure would add cost and latency for nothing.
|
|
|
|
## 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
|
|
│ └─ alerts/ AlertSource + ArpaCap implementation
|
|
├─ features/ one folder per screen or coherent UI area
|
|
│ ├─ map/ timeline/ alerts/ sources/
|
|
└─ 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. `AlertSource` follows 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 base map and the alerts still work; only the radar layer is empty.
|
|
- Base map tiles unreachable → MapLibre draws what it has; the radar overlay is
|
|
positioned geographically, not relative to the tiles, so it stays correct.
|
|
- 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. 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. With no advertising and no forecast
|
|
provider, nothing about the user leaves the device except the area the map is looking at,
|
|
which is inherent to any hosted base map.
|