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>
7.8 KiB
Roadmap
Each milestone ends with tool/verify.ps1 green and one commit. A milestone is not
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 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.
M0 — Toolchain and repository hygiene ✅
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.
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.
M1 — Scaffold, Italian l10n, region config, CI ✅
flutter create with applicationId it.nuvolari.app; flutter_localizations + intl
with app_it.arb as template and no hardcoded UI strings; RegionConfig loaded from
assets/regions/piemonte.json with parsing tests; .gitignore, env.example.json,
tool/verify.ps1, .gitea/workflows/ci.yml.
Done. All four stages green; the AAB carries applicationId it.nuvolari.app,
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.ps1is the verification that must pass.
M2 — Map, attribution, Sources screen ✅
MapLibre on OpenStreetMap tiles, permanent OSM/OpenMapTiles attribution, and a Sources / Licenses / Disclaimer screen with the explicit "not an official app" disclaimer.
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.
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), 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 more defects:
- The notifier wrote to
statefrom insidebuild(), which Riverpod rejects as an uninitialised provider. This broke startup, not just tests. - Eight-month-old demo frames rendered as "Aggiornato 342535 minuti fa". The age formatter now steps up to hours and days.
- Demo mode sat permanently behind a stale-data warning, so it never showed the
working state it exists to demonstrate.
MockRadarSourcenow shifts the bundled timestamps onto the present, leaving images, order and spacing untouched.
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 — Backend worker ⛔
The critical path. Until this exists, DpcRadarSource has nothing to read and the app
can only show demo frames.
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.
WebSocket trigger on wss://radar-wss.protezionecivile.it, with a 5-minute cron as
fallback.
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.
Blocked on (publishing only): VPS / object storage endpoint and credentials.
Development proceeds against LocalPublisher and a LAN python -m http.server.
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 — Play Store release preparation ⛔
Signing config reading key.properties, release AAB, target API 36, privacy policy,
store listing copy, Data safety declaration, 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.
Pending inputs from the project owner
| Needed for | Item |
|---|---|
| M4 | VPS / object storage endpoint and credentials |
| M6 | Firebase project and google-services.json |
| 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.
Verifying on the emulator
An AVD named nuvolari is set up on this machine: API 36.1, google_apis, x86_64,
GPU passthrough to the host. It uses a 2 GB data partition and no SD card because disk
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:
# Boot it (idempotent — returns at once if a device is attached)
powershell -File tool/start_emulator.ps1
# Build, install, launch
cd app
flutter build apk --debug
adb install -r build/app/outputs/flutter-apk/app-debug.apk
adb shell am start -n it.nuvolari.app/.MainActivity
# Capture what it looks like
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.