Add monorepo scaffolding and project documentation
Sets up the Nuvolari monorepo layout (app/, backend/, docs/, tool/) with the groundwork that does not depend on the Flutter toolchain: gitignore covering Flutter, Python and every secret file shape; env.example.json as the template for --dart-define-from-file; a verification script that skips stages whose target does not exist yet so it is runnable from day one; and a CI workflow in GitHub Actions syntax so it runs unchanged on Gitea or GitHub. The documentation records facts verified against the live services rather than restated from the brief. Two of them change the design: - DPC VMI rasters are 1200x1400 Float32 on a 1 km grid in a custom projection centred on Italy, not EPSG:4326 or EPSG:3857, and their GeoKeys are internally inconsistent. Reprojection is mandatory and the source CRS must be read from each file rather than hardcoded. - The ARPA CAP feed carries six level values, not four: BIANCO for the avalanche scale out of season and "-" for no data. Collapsing either into VERDE would report "no alert" where the bulletin reports "not assessed". Also documents why the frames we publish inherit CC BY-SA from the DPC source, and why rain notifications subscribe to cell topics from the device so no user location ever reaches a server. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,74 @@
|
||||
# Nuvolari
|
||||
|
||||
Precipitation radar for Piedmont, Italy. Android first, iOS later, one Flutter codebase.
|
||||
|
||||
Radar imagery comes from the public **Radar-DPC** platform, forecasts from **MET
|
||||
Norway**, weather alerts from the **ARPA Piemonte** XML-CAP bulletin. The app is free
|
||||
and ad-supported, with GDPR consent through Google's UMP.
|
||||
|
||||
Nuvolari is an independent app. It is not affiliated with, endorsed by, or operated by
|
||||
ARPA Piemonte or the Dipartimento della Protezione Civile. For civil-protection
|
||||
purposes the official channels always prevail.
|
||||
|
||||
## Layout
|
||||
|
||||
```
|
||||
app/ Flutter application (Dart package "nuvolari")
|
||||
backend/ Python worker: fetches DPC rasters, crops, reprojects, renders PNG frames
|
||||
docs/ architecture, data sources, licenses, stack decisions, roadmap, privacy
|
||||
tool/ verification scripts
|
||||
```
|
||||
|
||||
Start with [docs/architecture.md](docs/architecture.md), then
|
||||
[docs/roadmap.md](docs/roadmap.md) for what is built and what is next.
|
||||
|
||||
## Toolchain
|
||||
|
||||
| Tool | Version |
|
||||
|---|---|
|
||||
| Flutter | 3.47.3 stable (Dart 3.13.3) |
|
||||
| Android SDK | platform 36, build-tools 36.0.0, platform-tools |
|
||||
| JDK | 21 |
|
||||
| Python | 3.12+ (3.14 works; rasterio ships wheels for it) |
|
||||
|
||||
## Configuration
|
||||
|
||||
Secrets never enter the repository. Copy the template and fill it in:
|
||||
|
||||
```bash
|
||||
cp env.example.json env.json # env.json is git-ignored
|
||||
```
|
||||
|
||||
| Key | Purpose |
|
||||
|---|---|
|
||||
| `MAP_STYLE_URL` | MapLibre style URL. Empty falls back to a local offline style. |
|
||||
| `RADAR_MANIFEST_URL` | Base URL of the published `manifest.json`. |
|
||||
| `RADAR_SOURCE` | `mock` (offline demo), `dpc` (live), `arpa` (disabled stub). |
|
||||
| `METNO_USER_AGENT_CONTACT` | Contact address for the MET Norway User-Agent — **mandatory** for forecasts. |
|
||||
| `ADMOB_APP_ID`, `ADMOB_BANNER_UNIT_ID` | Empty means Google's test ad units are used. |
|
||||
|
||||
## Running
|
||||
|
||||
```bash
|
||||
cd app
|
||||
flutter run --dart-define-from-file=../env.json
|
||||
```
|
||||
|
||||
With no `env.json` the app starts in demo mode: mock radar frames from assets, offline
|
||||
base map style, test ad units. No network and no credentials required.
|
||||
|
||||
## Verifying
|
||||
|
||||
```powershell
|
||||
.\tool\verify.ps1 # format, analyze, test, build, lint, pytest
|
||||
.\tool\verify.ps1 -SkipBuild # fast inner loop
|
||||
```
|
||||
|
||||
Stages whose target does not exist yet are skipped, so this runs from day one.
|
||||
|
||||
## Attribution
|
||||
|
||||
Radar-DPC (CC BY-SA) · MET Norway (CC BY 4.0) · Arpa Piemonte ·
|
||||
© OpenStreetMap contributors (ODbL). See [docs/licenses.md](docs/licenses.md) for the
|
||||
obligations these carry — in particular, the rendered radar frames are a derived
|
||||
product of CC BY-SA data and inherit share-alike.
|
||||
Reference in New Issue
Block a user