Narrow scope to radar, and put the app on a real OpenStreetMap base map

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>
This commit is contained in:
2026-09-10 16:10:29 +02:00
co-authored by Claude Opus 5
parent 91f9ac0fbf
commit f3a0e3794a
20 changed files with 430 additions and 350 deletions
+37 -14
View File
@@ -9,16 +9,19 @@ Android ships first, iOS follows on the same code. Platform-specific work stays
interfaces (`core/platform/`) so the iOS port is additive rather than a rewrite.
Toolchain pinned during setup: **Flutter 3.47.3 stable / Dart 3.13.3**,
compileSdk/targetSdk **36**, minSdk **21** (the floor imposed by `maplibre_gl`),
JDK **21**.
compileSdk/targetSdk **36**, minSdk **24**, JDK **21**.
`maplibre_gl` only needs API 21; 24 is the floor `firebase_messaging` imposes
for the rain notifications, and it is Flutter's own default, so it is the
best-tested path.
## State management — Riverpod without code generation
`flutter_riverpod` with hand-written `Notifier` / `AsyncNotifier` classes.
Chosen over: Bloc (more ceremony than this app's state needs), plain `setState`
(the radar timeline, the frame cache and the consent flow all share state across
screens), Riverpod *with* `riverpod_generator`.
(the radar timeline, the frame cache and the alert state all cross screen
boundaries), and Riverpod *with* `riverpod_generator`.
Dropping code generation keeps `build_runner` out of CI and out of every edit-run
cycle. The generator's benefit — less boilerplate on providers — is small at this
@@ -26,12 +29,10 @@ size, and its cost is paid on every build. Reconsider if provider count passes ~
## Networking — Dio
`dio` with interceptors for: the mandatory MET Norway User-Agent, retry with
exponential backoff, and timeouts.
`dio` with interceptors for retry with exponential backoff and timeouts.
Chosen over `http`, which has no interceptor model — the User-Agent obligation is a
licensing requirement, so it belongs in one enforced place rather than at each call
site where it can be forgotten.
Chosen over `http` for the interceptor model: cross-cutting request policy belongs in
one enforced place rather than at each call site where it can be forgotten.
The DPC `origin` header lives **only in the Python worker**. The app never talks to
DPC directly.
@@ -39,7 +40,7 @@ DPC directly.
## Models — hand-written `fromJson`
Chosen over `freezed` + `json_serializable`. The model set is small (radar manifest and
frames, forecast series, CAP alerts, region config) and the parsers are covered by
frames, CAP alerts, region config) and the parsers are covered by
tests against real fixtures. Same rationale as Riverpod: no `build_runner`.
The tests, not the generator, are what guarantee the parsing is right — fixtures
@@ -53,9 +54,29 @@ Chosen over `flutter_map`, which renders tiles in Dart. Radar animation redraws
full-viewport image several times a second; a GPU-composited native renderer holds
frame rate where a Dart canvas does not.
The base map style URL comes from `MAP_STYLE_URL`. With no key configured the app
loads a minimal local style — flat background plus the Piedmont boundary from a
bundled GeoJSON — so development, tests and the demo mode all work offline.
## Base map — OpenFreeMap Positron
OpenStreetMap vector tiles from [OpenFreeMap](https://openfreemap.org): no API key, no
registration, no request limits, commercial use permitted.
Chosen over MapTiler, Stadia, Jawg and Thunderforest, whose free tiers all require a key.
A key 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: the radar overlay has to be the loudest thing on
screen, and Positron is a desaturated grey base built to sit under data. On a full-colour
style the precipitation ramp competes with road casings and landuse fills.
The trade is a dependency on someone else's free service. The escape hatch is
self-hosting — OpenFreeMap is MIT-licensed and publishes its planet tiles — and
`MAP_STYLE_URL` already points the app anywhere else without a code change.
Its style JSON carries no `attribution` field, so MapLibre shows no credits by itself and
the app renders them from the region config. See [licenses.md](licenses.md).
`MAP_STYLE_URL=offline` selects a style generated from the region bounding box, with no
network sources at all: a flat background and the extent outline. Deliberately plain so
it is never mistaken for a finished map, and it is what the widget tests run against.
## Radar frame rendering — image source, double buffered
@@ -97,7 +118,9 @@ centre and zoom limits, alert zones, active data sources, attribution strings. A
a region is a new JSON file plus its assets — no Dart changes.
Piedmont bounding box, padded: `[6.55, 43.95, 9.30, 46.55]` (W, S, E, N).
To be refined against the ISTAT geometry once that dataset is confirmed.
It is a render extent, not an administrative boundary: it deliberately overshoots
the region so nothing is clipped at the edges, and the tests assert that every
provincial capital falls inside it.
## Backend — Python worker on a VPS