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>
147 lines
6.8 KiB
Markdown
147 lines
6.8 KiB
Markdown
# Stack decisions
|
||
|
||
Each entry records what was chosen, what it was chosen over, and why. Revisit an entry
|
||
only with a reason that invalidates its rationale.
|
||
|
||
## Flutter, single codebase
|
||
|
||
Android ships first, iOS follows on the same code. Platform-specific work stays behind
|
||
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 **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 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
|
||
size, and its cost is paid on every build. Reconsider if provider count passes ~40.
|
||
|
||
## Networking — Dio
|
||
|
||
`dio` with interceptors for retry with exponential backoff and timeouts.
|
||
|
||
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.
|
||
|
||
## Models — hand-written `fromJson`
|
||
|
||
Chosen over `freezed` + `json_serializable`. The model set is small (radar manifest and
|
||
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
|
||
captured from the real endpoints catch schema drift that codegen would not.
|
||
|
||
## Map — MapLibre GL
|
||
|
||
`maplibre_gl` 0.27.0 (Flutter 3.29+, Android API 21+, iOS 13+).
|
||
|
||
Chosen over `flutter_map`, which renders tiles in Dart. Radar animation redraws a
|
||
full-viewport image several times a second; a GPU-composited native renderer holds
|
||
frame rate where a Dart canvas does not.
|
||
|
||
## 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
|
||
|
||
The worker publishes each frame already cropped to the region bounding box and
|
||
reprojected to EPSG:3857, so the four corners of a MapLibre `LatLngQuad` are exact and
|
||
no client-side warping is needed.
|
||
|
||
Animation uses **two image sources, A and B**: while one is visible the next frame is
|
||
decoded into the other, then visibility swaps.
|
||
|
||
Chosen over: adding all ~20 frames as layers with opacity 0 (constant GPU memory
|
||
matters more than the saved swap — 20 frames at 1024×1024 RGBA is ~80 MB resident),
|
||
and over updating a single source in place (visible flicker during decode).
|
||
|
||
## Frame cache — custom in-memory LRU
|
||
|
||
`FrameCache`: an in-memory LRU of PNG bytes with a byte budget, plus `retainOnly` so
|
||
the timeline can drop everything outside the window around the playhead.
|
||
|
||
The budget is in bytes rather than entries because frame size tracks how much
|
||
precipitation is on screen — a clear sky compresses to almost nothing, a storm does
|
||
not — so an entry count would let a stormy loop use several times the memory of a calm
|
||
one.
|
||
|
||
Chosen over `flutter_cache_manager`, which does not expose the eviction control the
|
||
scrubber needs. Plain LRU keeps frames the prefetcher touched a moment ago even after
|
||
the playhead has moved to the far end of the timeline, so eviction is driven by
|
||
distance from the playhead, not by access time.
|
||
|
||
**Deliberately not persistent.** Mock frames already live in the asset bundle, and
|
||
network frames are re-fetched from the CDN. A disk layer belongs with the network
|
||
adapter, where it would actually save a request, and is worth adding once real CDN
|
||
frames are flowing.
|
||
|
||
## Region configuration
|
||
|
||
Everything region-specific lives in `app/assets/regions/<id>.json`: bounding box, map
|
||
centre and zoom limits, alert zones, active data sources, attribution strings. Adding
|
||
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).
|
||
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
|
||
|
||
GDAL and HDF5 cannot run on Supabase Edge Functions (Deno), so the worker runs as a
|
||
scheduled process on a VPS or Cloud Run.
|
||
|
||
`rasterio` 1.5.1 publishes Windows wheels for Python 3.14, so the worker also runs
|
||
natively on the development machine — no Docker or WSL needed to iterate.
|
||
|
||
Trigger: the DPC WebSocket push channel `wss://radar-wss.protezionecivile.it`, with a
|
||
5-minute cron as fallback. Polling DPC on a timer is the fallback, never the norm.
|
||
|
||
Output goes through a `Publisher` interface: `LocalPublisher` writes to `backend/out/`
|
||
for development, `S3Publisher` targets R2 or Supabase Storage once credentials exist.
|
||
|
||
## Rain notifications — client-side topic subscription
|
||
|
||
The worker computes rain per **geographic cell** and publishes per-cell state. The app
|
||
subscribes to FCM topics named after cells, **from the device**.
|
||
|
||
The server therefore never learns any user's position — not precisely, not even by
|
||
cell. There is no user table to leak, and Data safety can honestly declare that no
|
||
location is transmitted or stored.
|