Alby96/Europa
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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:
Alby96
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
Download Patch File Download Diff File Expand all files Collapse all files
Nuvolari/docs/roadmap.md
+78 -83
View File
@@ -1,9 +1,13 @@
# Roadmap
Each milestone ends with `tool/verify.ps1` green and one commit. A milestone is not
done until its acceptance criteria hold.
done until its acceptance criteria hold, **and until it has been seen running on the
emulator** — twice now that step has caught defects the tests did not.
Legend: ✅ done · 🔨 in progress · ⛔ blocked on credentials from the project owner
Legend: ✅ done · 🔨 in progress · ⛔ blocked on something the project owner must supply
> **Scope**: radar on a map, official alerts, rain notifications. Forecasts, lightning,
> a home-screen widget and advertising are all out — see CLAUDE.md.
---
@@ -12,14 +16,10 @@ Legend: ✅ done · 🔨 in progress · ⛔ blocked on credentials from the proj
Flutter 3.47.3 stable, Android SDK (platform-tools, platform 36, build-tools 36.0.0),
JDK 21, environment variables. Commit the removal of the old Xamarin skeleton.
**Accepts when:** `flutter doctor -v` reports no blocking Android toolchain error and
`git status` is clean.
**Done.** `flutter doctor -v` reports "No issues found!". Installed: Flutter 3.47.3 at
`C:\src\flutter` (telemetry disabled), Android SDK at `C:\Android\Sdk` with
platform 36, build-tools 36.0.0, platform-tools and all licences accepted, and
`JAVA_HOME` pointing at the JDK 21 a previous Visual Studio install had already left
on the machine.
`C:\src\flutter` (telemetry disabled), Android SDK at `C:\Android\Sdk` with platform 36,
build-tools 36.0.0, platform-tools and all licences accepted, and `JAVA_HOME` pointing at
the JDK 21 a previous Visual Studio install had already left on the machine.
## M1 — Scaffold, Italian l10n, region config, CI ✅
@@ -28,52 +28,41 @@ with `app_it.arb` as template and no hardcoded UI strings; `RegionConfig` loaded
`assets/regions/piemonte.json` with parsing tests; `.gitignore`, `env.example.json`,
`tool/verify.ps1`, `.gitea/workflows/ci.yml`.
**Accepts when:** `flutter analyze` reports 0 issues, `flutter test` passes,
`flutter build appbundle --debug` succeeds.
**Done.** All four stages green; the AAB carries applicationId `it.nuvolari.app`,
minSdk 24, targetSdk 36. 50 tests, including assertions against the shipped Piemonte
asset and a captured copy of the live ARPA CAP feed.
minSdk 24, targetSdk 36. Tests assert against the shipped Piemonte asset and a captured
copy of the live ARPA CAP feed.
> The Gitea instance may have no Actions runner. The workflow file is written to be
> GitHub-Actions compatible, but `tool/verify.ps1` is the verification that must pass.
## M2 — Map, attribution, Sources screen ✅
MapLibre with the style from `MAP_STYLE_URL`, falling back to a local minimal style.
Permanent OSM/ODbL attribution. Sources / Licenses / Disclaimer screen covering
Radar-DPC (CC BY-SA), MET Norway, ARPA, OSM, with the explicit "not an official app"
MapLibre on OpenStreetMap tiles, permanent OSM/OpenMapTiles attribution, and a
Sources / Licenses / Disclaimer screen with the explicit "not an official app"
disclaimer.
**Accepts when:** the map opens centred on Piedmont, attribution is visible at all
times, and the Sources screen is reachable and complete.
**Done and verified on the emulator.** The attribution bar lists only the sources
actually rendered — crediting OpenStreetMap while showing the offline fallback would be
a false attribution — and sits below the map, inside a SafeArea, so neither a map control
nor the system gesture pill can cover a credit the licences require to be visible.
**Done**, with one gap. The fallback style is generated from the region bounding box
rather than loaded from an asset, so it needs no third-party boundary dataset and no
network. The attribution bar lists only the sources actually rendered — crediting
OpenStreetMap while showing the fallback would be a false attribution — and sits below
the map rather than floating over it so no map control can occlude it.
**Verified on an emulator** (`nuvolari`, API 36.1, x86_64, GPU host). Running it caught
two things the unit tests could not: the configured initial zoom put the viewport
entirely inside the region so the map read as a blank expanse, and the attribution bar
sat behind the system gesture pill. Both fixed — the camera now fits the region bounds
at runtime, which works on any screen size, and the bar is inside a SafeArea.
Running it caught two defects the unit tests could not: the configured initial zoom put
the viewport entirely inside the region so the map read as a blank expanse, and the
attribution bar sat behind the gesture pill. The camera now fits the region bounds at
runtime, which works at any screen size.
## M3 — Animation and timeline ✅
`RadarSource` with `MockRadarSource` (synthetic frames in assets) and `DpcRadarSource`.
Timeline scrubber, play/pause, adjacent-frame prefetch, `FrameCache` LRU, animation
suspended in background, graceful degradation with a data-age banner.
**Accepts when:** animation runs smoothly in demo mode **with the network off**, and
prefetch, LRU eviction and the fallback paths are covered by tests.
`RadarSource` with `MockRadarSource` (synthetic frames in assets), `DpcRadarSource`
(reads our CDN) and `ArpaRadarSource` (disabled stub). Timeline scrubber, play/pause,
adjacent-frame prefetch, `FrameCache` LRU, animation suspended in background, graceful
degradation with a data-age banner.
**Done and verified on the emulator.** The overlay is double buffered, the timeline
lands on the newest frame, playback advances and wraps, scrubbing takes over from
playback, and the legend is drawn from the manifest rather than a constant.
Running it caught three things the tests had not:
Running it caught three more defects:
- The notifier wrote to `state` from inside `build()`, which Riverpod rejects as an
uninitialised provider. This broke startup, not just tests.
@@ -86,54 +75,60 @@ Running it caught three things the tests had not:
Frame caching is in memory only for now: mock frames are already in the asset bundle
and a disk layer belongs with the network adapter, where it would save a real request.
## M4 — Forecast
---
`MetNoForecastSource` with the mandatory identifying User-Agent, honouring `Expires`
and `If-Modified-Since`. `IconIt2Source` as a flagged fallback. Hourly and daily views.
## M4 — Backend worker ⛔
**Accepts when:** a forecast renders for a Piedmont location, caching respects the
response headers, and fixture-based tests pass.
The critical path. Until this exists, `DpcRadarSource` has nothing to read and the app
can only show demo frames.
## M5 — UMP consent and AdMob ⛔
`backend/nuvolari_worker/`: `dpc_client` (with the `origin` header), `crop` (bbox +
reproject to EPSG:3857 — the source CRS is read from each file, never assumed),
`palette` (dBZ colormap, legend exported into the manifest), `render` (RGBA PNG,
transparent below threshold), `manifest`, and a `publisher/` with `LocalPublisher` and
`S3Publisher`. Also fetches the ARPA CAP bulletin and publishes `alerts.json`, so the
app never polls ARPA directly.
UMP consent form before any ad request; non-personalised ads when consent is declined.
Anchored adaptive banner — never over the map, never an interstitial during animation.
**Test ad unit IDs only** until real ones are supplied.
WebSocket trigger on `wss://radar-wss.protezionecivile.it`, with a 5-minute cron as
fallback.
**Blocked on:** AdMob App ID and ad unit IDs.
**Accepts when:** `python -m pytest` passes and one full run produces PNGs plus a
`manifest.json` that the app consumes from a local server, showing real Piedmont
precipitation on the emulator.
## M6 — Rain notifications and alerts ⛔
**Blocked on (publishing only):** VPS / object storage endpoint and credentials.
Development proceeds against `LocalPublisher` and a LAN `python -m http.server`.
`ArpaCapAlertSource` reading the CAP feed through the backend; zones `Piem-A`…`Piem-M`
with levels shown verbatim and a link to the official bulletin. Rain notifications via
FCM topics per geographic cell, subscribed from the device.
## M5 — Official alerts
`ArpaCapAlertSource` reading `alerts.json` from our CDN. Zones `Piem-A`…`Piem-M` with
levels shown **verbatim** and a link to the official bulletin next to every one.
Six level values, not four: `VERDE`, `GIALLO`, `ARANCIONE`, `ROSSO`, plus `BIANCO`
(avalanche scale, out of season) and `-` (not published). `BIANCO` and `-` are their own
state and must never be collapsed into `VERDE` — that would report "no alert" where the
bulletin reports "not assessed".
**Accepts when:** the eleven zones render with the levels the live feed carries, the
captured fixture parses, and every alert view links the official bulletin.
## M6 — Rain notifications ⛔
FCM topics per geographic cell, subscribed **from the device**, so no user location ever
reaches a server. The worker publishes per-cell rain state.
**Accepts when:** subscribing and unsubscribing works, and a published cell state
produces a notification on the emulator.
**Blocked on:** Firebase project and `google-services.json`.
## M7 — Android home widget
## M7 — Play Store release preparation ⛔
Glance widget showing the latest frame and the next rain, refreshed by WorkManager.
Signing config reading `key.properties`, release AAB, target API 36, privacy policy,
store listing copy, Data safety declaration, prominent disclosure for location.
**Accepts when:** the widget renders a real frame on the home screen and updates.
## M8 — Backend worker ⛔
`dpc_client` (with the `origin` header), `crop` (bbox + reproject to EPSG:3857),
`palette` (dBZ colormap, legend exported into the manifest), `render` (RGBA PNG,
transparent below threshold), `manifest`, and `publisher/` with `LocalPublisher` and
`S3Publisher`. WebSocket trigger with cron fallback. pysteps nowcast present but
disabled behind a flag.
**Accepts when:** `python -m pytest` passes and one full run produces PNGs plus a
`manifest.json` that the app consumes from a local server.
**Blocked on (publishing only):** VPS / object storage endpoint and credentials.
Development proceeds against `LocalPublisher`.
## M9 — Play Store release preparation ⛔
Signing config reading `key.properties`, release AAB, target API 36, privacy policy
draft, store listing copy, Data safety draft, prominent disclosure for location.
Data safety is unusually simple here: no advertising, no analytics, no accounts, and no
location leaving the device.
**Blocked on:** upload keystore and Play Console account.
@@ -143,11 +138,12 @@ draft, store listing copy, Data safety draft, prominent disclosure for location.
| Needed for | Item |
|---|---|
| M2 (quality) | MapTiler API key — until then the local fallback style is used |
| M5 | AdMob App ID and ad unit IDs |
| M4 | VPS / object storage endpoint and credentials |
| M6 | Firebase project and `google-services.json` |
| M8 | VPS / object storage endpoint and credentials |
| M9 | Play Console account and upload keystore |
| M7 | Play Console account and upload keystore |
| ARPA radar adapter | The email to `info.meteo@arpa.piemonte.it` asking for the real-time access link **and the reuse licence**. Free of charge is not a licence, and without stated terms the frames cannot be republished. |
Nothing is needed for the base map: OpenFreeMap requires no key and no account.
---
@@ -158,9 +154,12 @@ GPU passthrough to the host. It uses a 2 GB data partition and no SD card becaus
is tight, and quickboot snapshots are disabled — they cost 2.6 GB to save a few seconds
of boot, which is the wrong trade here. Expect a cold boot of a minute or so.
In VS Code, just press **F5**: every emulator debug configuration boots it first. From a
shell:
```bash
# Boot it
"$ANDROID_HOME/emulator/emulator" -avd nuvolari -no-audio -no-boot-anim -gpu host
# Boot it (idempotent — returns at once if a device is attached)
powershell -File tool/start_emulator.ps1
# Build, install, launch
cd app
@@ -174,7 +173,3 @@ adb exec-out screencap -p > screen.png
`flutter run -d emulator-5554` works too and gives hot reload; the steps above are what
a non-interactive session uses.
> An unrelated AVD, `pixel_7_-_api_35`, is present but broken — its system image
> (`android-35/google_apis_playstore`) is not installed, so it cannot boot. It occupies
> about 4.8 GB. It predates this project and has been left alone.