Alby96andClaude Opus 5
06ab816ebe
A saved place is a named point the user keeps: it frames the map now, and once the worker publishes station data it is what the nearest-station readings and, later, the rain notifications will hang off. Free points rather than stations, because people think in terms of home and work, not in terms of which weather station happens to represent them. Everything stays on the device. Places live in SharedPreferences under a versioned key, and there is no account to attach them to and no server that would accept them. That is what keeps the Data safety declaration able to say no location is collected, and it must survive the notification work: the device will subscribe to the topic for the cell containing a place, so the link between a person and a place never leaves their phone. Location is coarse only, and that took enforcing. geolocator declares ACCESS_FINE_LOCATION in its own manifest and the merger pulls it in, so the system dialog offered "Precise" despite the app asking for nothing of the sort; the manifest now removes it with tools:node="remove", and the dialog reads "approximate location" with no choice offered. Requests also go through the platform LocationManager rather than the Play Services fused provider, which prompts about Location Accuracy and, when declined, returns no fix at all — an absurd outcome for an app that only ever wanted an approximate one, and one that also tied location to Play Services being present. The prominent disclosure comes before the system dialog, as Play requires, and is repeated in Settings so someone who already answered can still read what the permission is for. Declining leaves the app fully usable. Two more defects found by running it and by a test: - MapLibreMap leaves cameraPosition null unless trackCameraPosition is set, so "save the map centre" silently saved the region default rather than what the user was looking at. - Place ids came straight from the microsecond clock, so two places saved in the same microsecond shared an id and rename, remove and the duplicate-name check all acted on the wrong one. A test caught it on a fast machine. Saving refuses points outside the region rather than accepting them: a place in Rome would look like it worked and then show nothing forever. Also corrects CLAUDE.md, which still said ARPA states no licence, and records the ARPA realtime API there with the property that governs how it may be used — it lags about 4.5 hours, so it is an observation archive and must never sit next to 5-minute radar looking current. Verified: analyze clean, 158 tests passing, and on the emulator the disclosure precedes the system dialog, the dialog asks only for approximate location, a place survives restart and reinstall, and tapping one moves the map onto it. 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/ places/ settings/ 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.
|