🐟

GeoData Fishing

Piattaforma serverless per il tracciamento delle catture di pesca con arricchimento geo-meteorologico automatico da 7+ API pubbliche in tempo reale

⚡ CLOUDFLARE WORKERS · D1 · R2 · HONO v4
📋 v2.0.0 👤 Giuseppe Scotto Lavina · Ramon Fede 📅 Maggio 2026 🧪 904 Test · 47 File · 94% Coverage 🔒 Security Audit Completato
01 — Panoramica
Cos'è GeoData Fishing
Un sistema completo per registrare catture di pesca, arricchendole automaticamente con oltre 30 datapoint geo-meteorologici e scientifici in tempo reale. Zero API key richieste, 100% serverless.
🎯
Problema Risolto
Il contesto della cattura

Quando un pescatore cattura un pesce, le condizioni ambientali — meteo, pressione barometrica, fase lunare, livello dell'acqua — sono cruciali per capire perché il pesce ha abboccato. GeoData acquisisce automaticamente tutti questi dati dal GPS del telefono, senza alcun input manuale.

💡
Approccio Tecnico
Resilienza con Promise.allSettled

Il sistema aggrega dati da 7+ API pubbliche gratuite in parallelo tramite Promise.allSettled. Se un provider è down, gli altri compensano. Un indicatore data_quality (0-100) traccia la completezza dei dati per ogni cattura.

📊 Dati Raccolti Automaticamente per Cattura

🌡️
Meteo Completo

Temperatura, umidità, pressione, trend barometrico, vento (velocità + direzione + raffica), copertura nuvolosa, precipitazioni, UV index

📍
Geolocalizzazione

Reverse geocoding completo via Nominatim: città, provincia, via, indirizzo formattato, geohash a 7 caratteri per query di prossimità

🌙
Dati Lunari & Solunari

Fase lunare (8 fasi), illuminazione %, periodi solunari major/minor, day rating 1-5, transiti Moon Overhead/Underfoot

💧
Corpi d'Acqua

Fiumi, laghi, canali, stagni nel raggio di 10km via Overpass API (OpenStreetMap). Dighe nel raggio di 50km con altezza e materiale

🧲
Geomagnetico (Kp)

Indice Kp planetario 0-9 da NOAA SWPC. Campo magnetico terrestre calmo (Kp≤2) = ottimo per la pesca

🌊
Livelli Idrometrici

Dati real-time dalla rete AEGIS Regione Lazio — livello fiume in metri, trend, stazione più vicina con distanza

🌅
Dati Solari

Orario alba/tramonto, flag giorno/notte, bonus twilight calcolato per la "golden hour" di pesca

🌊
Maree

Predizioni maree via Open Tide API (modello TPXO9-v5), altezze e tempi delle prossime 24 ore

🔬
Dati Scientifici

Temperatura acqua stimata (con lag stagionale), delta temperatura 24h, fishing score composito 0-100 su 8 fattori

55+ colonne vengono salvate per ogni cattura nel database D1, rendendo ogni record un dataset completo per analisi statistiche e correlazioni specie-condizioni.
02 — Architettura
Infrastruttura Cloudflare
Architettura 100% serverless su Cloudflare Workers. Un singolo deploy gestisce API, database, storage foto e hosting frontend. Zero server da mantenere.
Architettura di Sistema — Cloudflare Edge
📱 Mobile Browser
GPS + Camera API
▼ HTTPS ▼
📄 Static Assets
web/ → CDN
←
⚡ Hono Worker
src/worker.js
→
🗃️ D1 Database
SQLite Edge
📦 R2 Bucket
Foto Catture
▼ Promise.allSettled ▼
Open-Meteo
METEO PRIMARY
Yr.no
METEO FALLBACK
Nominatim
GEOCODING
Overpass
OSM WATER
NOAA SWPC
Kp INDEX
AEGIS Lazio
WATER LEVEL
Open Tide
TIDES

☁️ Servizi Cloudflare — Dettaglio

⚡
Workers
Runtime serverless V8 isolate sull'edge globale
  • Cosa: Runtime JavaScript V8 isolates distribuito su 300+ data center Cloudflare
  • Perché: Zero cold start, latenza <50ms, auto-scaling, zero infrastruttura da gestire
  • Come: Framework Hono v4 — routing, middleware CORS, security headers built-in
  • Entry point: src/worker.js — esporta l'app Hono come export default app
  • Dev locale: wrangler dev --local con D1/R2 simulati localmente
🗃️
D1 (SQLite Edge)
Database relazionale co-locato con il worker
  • Cosa: SQLite distribuito con binding DB diretto nel worker context
  • Perché: Zero latenza DB (co-locato), SQL standard, schema versionato con migration
  • Come: Data Access Layer in repository.js — tutte le query passano dal DAL
  • Schema: 6 tabelle, 9 indici, 55+ colonne su catches, FK con CASCADE
  • Sicurezza: Sempre .bind() per parametri, mai concatenazione SQL
📦
R2 (Object Storage)
S3-compatibile, zero egress fee
  • Cosa: Storage binario per foto catture con binding PHOTOS
  • Perché: Zero costi di egress (a differenza di S3), API S3-compatibile
  • Come: Upload in catches.js via c.env.PHOTOS.put()
  • Organizzazione chiavi: catches/{catchId}/{timestamp}-{filename}
  • Limiti: Max 10MB/file, MIME whitelist (jpeg, png, webp, heic)
📄
Static Assets
CDN globale, zero build step
  • Cosa: La directory web/ viene servita come CDN globale Cloudflare
  • Perché: Zero build step, cache automatica, same-origin con l'API (no CORS issues)
  • Config: [assets] directory = "./web" in wrangler.toml
  • Frontend: Vanilla JS SPA, CSS glassmorphic dark mode, Leaflet + Chart.js per mappe e grafici
  • PWA: Service Worker Workbox, manifest installabile, icone custom Nautilus, aggiornamento via toast persistente
  • Zero CDN: Leaflet, Chart.js, Workbox e Inter font serviti da web/ — nessuna dipendenza esterna a runtime

📁 Struttura del Progetto

GeoData/ ├── src/ ← CODICE PRODUZIONE (Cloudflare Workers) │ ├── worker.js Entry point Hono — middleware, routing, error handler │ ├── config/ │ │ └── geo.json Cache config (100m radius, 30min TTL), provider config │ ├── db/ │ │ ├── schema.sql Schema D1 completo (CREATE TABLE IF NOT EXISTS) │ │ ├── migrations/ ALTER TABLE per evoluzione incrementale │ │ │ ├── 003_water_levels.sql │ │ │ ├── 004_bait_presentation.sql │ │ │ ├── 005_locations.sql ★ Tabella geo-fencing luoghi │ │ │ ├── 006_dedup_catches.sql UNIQUE(timestamp, angler_name) — colonne esplicite │ │ │ └── 007_fix_column_scramble.sql Ripristino colonne scrambled da 006 │ │ └── repository.js ★ Data Access Layer — TUTTE le query D1 (~988 righe) │ ├── routes/ │ │ ├── catches.js CRUD catture + upload foto R2 + validazioni │ │ ├── sessions.js CRUD sessioni di pesca │ │ ├── tags.js CRUD tag + associazione M:N a catture │ │ ├── photos.js Serve foto da R2 (GET, pubblico senza API key) │ │ ├── geo.js GET geo-data live senza salvare │ │ ├── analytics.js Analitiche specie/location aggregate │ │ ├── admin.js ★ Admin API — import/export, locations CRUD, erase-all │ │ └── admin-ui.js ★ Admin HTML UI glassmorphic (~1700 righe) │ └── lib/ │ ├── geo-data.js ★ Orchestratore principale — Promise.allSettled 7 API │ ├── weather.js Bridge verso weather-manager + historical │ ├── location.js Nominatim + Overpass (water bodies, dams) + Tides │ ├── scientific.js NOAA Kp, stima temp acqua, twilight bonus │ ├── lunar.js Fase lunare + periodi solunari (calcolo locale) │ ├── fishing-score.js Score 0-100 basato su 8 fattori pesati │ ├── cache.js In-memory radial cache (Map, TTL, Haversine, cap 100) │ ├── water-level.js ★ AEGIS Lazio — livello idrometrico (OAuth2) │ ├── utils.js haversine, geohash, cardinal, weather descriptions │ └── providers/ │ ├── weather-manager.js Orchestratore waterfall tra provider meteo │ ├── open-meteo.js Provider primario meteo (10K req/giorno) │ └── yr-no.js Provider fallback MET Norway │ ├── web/ ← FRONTEND (Cloudflare Static Assets + PWA) │ ├── index.html SPA entry — dual nav, intro video overlay, Leaflet/Chart.js SRI │ ├── sw.js ★ Service Worker Workbox v7.4.0 — precache + runtime caching │ ├── manifest.json PWA manifest — Nautilus Carpfishing, icone, theme │ ├── css/app.css Design system glassmorphic dark mode (~2300 righe) │ ├── css/vendor/ │ │ └── leaflet.css Leaflet maps CSS (self-hosted) │ ├── js/ │ │ ├── app.js Entry point e SPA initialization (~110 righe) │ │ ├── api.js Client API — fetch con X-API-Key header (~156 righe) │ │ ├── chart-builder.js Chart.js wrapper per grafici avanzati (~340 righe) │ │ ├── constants.js Costanti globali, DOM selectors e form options │ │ ├── state.js Global state manager reattivo (singleton store) │ │ ├── views/ Moduli visuali: capture.js, gallery.js, stats.js │ │ ├── components/ UI isolati: autocomplete, modal, photo-viewer, exif-confirm, location-picker, geo-edit-sheet │ │ ├── utils/ Utility pure: router.js, geo.js, image.js, helpers.js, exif.js, storage.js, persistence.js │ │ └── vendor/ ★ Librerie self-hosted: leaflet.js, chart.umd.js, workbox-sw.js │ └── assets/ │ ├── logo-topbar.png Medaglione logo Nautilus per header │ ├── logo-splash-cropped.webp Logo HD per intro animata iniziale │ ├── intro-mobile.mp4 Animazione intro premium con skip (video) │ ├── hero-bg-nautilus.png Background hero │ ├── nav-capture.png Icona navigazione Cattura │ ├── nav-gallery.png Icona navigazione Galleria │ ├── nav-stats.png Icona navigazione Stats │ └── icons/ PWA icons (512, 192, 180, 32, 16px) │ ├── scripts/ │ ├── bump-sw.mjs Auto-bump APP_VERSION in sw.js pre-deploy │ └── lighthouse-audit.mjs Audit Lighthouse programmatico (Puppeteer) │ ├── tests/ ← 30 file test, 616 test, 1250 assertions, ~7s ├── wrangler.toml Config Workers/D1/R2/Assets └── package.json Solo 2 deps: hono + wrangler
Dipendenze minimali: L'intero progetto ha solo 2 dipendenze — hono (runtime) e wrangler (dev/deploy). Zero bundler, zero framework frontend, zero ORM. Tutto vanilla JavaScript.
03 — Fonti Dati
Provider API Esterni
Ogni cattura viene arricchita con dati da 7+ API pubbliche gratuite, orchestrate dal modulo geo-data.js tramite Promise.allSettled per massima resilienza.
ProviderModuloDati FornitiRate LimitTimeoutFallback
Open-Meteoopen-meteo.jsTemp, pressione, vento, umidità, UV, precipitazioni, temp ieri per delta10K/giorno8s→ Yr.no
Yr.no (MET Norway)yr-no.jsStessi dati meteo, formato MET Norway compactUser-Agent req.8sUltimo nella catena
Nominatim (OSM)location.jsReverse geocoding: città, provincia, via, indirizzo formattato1 req/sec!10s—
Overpass API (OSM)location.jsCorpi d'acqua vicini (fiumi, laghi, canali) + dighe con altezza~10K/giorno15sMirror FR
NOAA SWPCscientific.jsIndice geomagnetico planetario Kp (0-9)Free5s→ null
AEGIS Regione Laziowater-level.jsLivello idrometrico real-time, trend, stazione, distanzaFree (OAuth2)10s→ skip
Open Tide APIlocation.jsPredizioni maree (TPXO9-v5), altezze, tempi prossime 24hFree8s→ skip

🔄 Weather Provider Waterfall

Il modulo weather-manager.js implementa un pattern waterfall iterativo: prova i provider nell'ordine configurato in geo.json. Se il primo fallisce, passa al successivo automaticamente.

1
Open-Meteo (primario)

API meteo gratuita con forecast corrente e dati storici dal 1940. Fornisce temperature_2m_mean del giorno precedente per il calcolo delta temperatura 24h. Include dati orari per il calcolo del trend barometrico su 6 ore.

2
Yr.no — MET Norway (fallback)

Se Open-Meteo è down, timeout o rate-limited, il manager tenta Yr.no. Richiede User-Agent obbligatorio. Non fornisce delta temp 24h (campo → null nel frontend) né dati storici.

3
Graceful Degradation

Se tutti i provider meteo falliscono, il campo weather è null ma la cattura viene comunque salvata con tutti gli altri dati (lunar, location, water). Il campo data_quality riflette il degrado (es. 85% invece di 100%).

🌊 Integrazione AEGIS Lazio — Dettaglio

🌊
Rete Idrometeorologica Regione Lazio
temporeale.regione.lazio.it/datascapeA

Autenticazione

  • Protocollo: OAuth2 Resource Owner Password Grant
  • Credenziali: AegisPubblico / AegisPubblico (pubbliche, embedded nel JS del portale)
  • Token caching: In-memory per isolate, con refresh 60s prima della scadenza

Endpoint

  • POST /connect/token — OAuth2 token
  • GET /v3/locations — Lista stazioni con coordinate
  • GET /v3/elements — Letture sensori live

Logica di Selezione Stazioni

  • Filtra stazioni con hwl: true (ha sensore idrometrico)
  • Calcola distanza con Haversine da coordinate utente
  • Filtra per raggio massimo (default 30km)
  • Restituisce le 3 stazioni più vicine
  • Matching sensore: elementName === 'Water Level' o contiene "idrometro"/"livello"

Dati Restituiti

  • Nome stazione, ID, coordinate, altitudine
  • Livello acqua in metri, trend in m, timestamp lettura
  • Stato sensore (0 = normale)

⚡ Radial Cache System

La cache in-memory usa un lookup spaziale Haversine: se una richiesta arriva da coordinate entro 100m di una precedente, restituisce il dato dalla cache. TTL 30 minuti, cap a 100 entry con eviction FIFO (oldest key). Si resetta al restart del worker isolate — accettabile perché Workers sono stateless by design.

04 — Algoritmo
Fishing Score Scientifico
Un punteggio 0-100 basato su 8 fattori ambientali pesati scientificamente, calcolato in fishing-score.js con base 50 e fattori additivi/sottrattivi.
FattorePesoLogicaFondamento Scientifico
Pressione Barometrica±20Rising fast +20 · Rising +10 · Stable +5 · Falling -5 · Fast -15Variazione pressione altera la vescica natatoria
Fase Lunare±15New/Full moon +15 · Near new/full +5Gravità lunare influenza maree e attività
Periodo Solunar±15Major (overhead/underfoot) +15 · Minor (rise/set) +8Teoria di J.A. Knight — transit lunari = picchi
Condizioni Meteo±10Nuvoloso≥60% +5 · Vento leggero +3 · Pioggia leggera +3 · Pioggia -10Luce ridotta attiva i predatori
Indice Kp±8Calmo ≤2 +8 · Moderato ≤4 +3 · Tempesta ≥6 -8Campo geomagnetico influenza sensori laterali
Crepuscolo+10Golden hour alba/tramonto, bonus proporzionale alla vicinanzaTransizione luce = picco attività predatoria
Delta Temp 24h±5Stabile <3°C +5 · Rapido >8°C -5Pesci ectotermici sensibili a shock termici
Temp Acqua Stimata±5Ottimale 15-22°C +5 · Buona 10-25°C +2 · Estrema -5Range metabolico ideale delle specie

🏷️ Classificazione

80-100 Excellent
65-79 Good
50-64 Fair
35-49 Poor
0-34 Bad
🧮 Formula Pseudocode
let score = 50; // base score += pressureTrend; // ±20 (trend barometrico 6h) score += lunarPhase; // ±15 (new/full moon bonus) score += solunarPeriod; // ±15 (major/minor feeding) score += weatherConditions;// ±10 (nuvole, vento, pioggia) score += kpIndex; // ±8 (geomagnetico NOAA) score += twilightBonus; // +10 (golden hour) score += tempDelta24h; // ±5 (stabilità termica) score += waterTemp; // ±5 (range ottimale) score = Math.max(0, Math.min(100, score));
05 — Database
Schema D1 (SQLite Edge)
Database SQLite distribuito sull'edge Cloudflare con 5 tabelle, 8 indici, foreign keys con CASCADE e schema versionato con migration incrementali.
catches (55+ colonne — timestamp, geo, meteo, lunar, solunar, scientific, water level, catch) ├── catch_photos (r2_key, thumbnail, metadata) → FK ON DELETE CASCADE ├── catch_tags (associativa M:N catch↔tag) → FK ON DELETE CASCADE (entrambe) │ └── tags (name UNIQUE, color #RRGGBB) └── sessions (name, start/end, location) → catches.session_id SET NULL locations (★ geo-fencing — name, water_name, water_type, lat, lon, radius_m, notes)

📇 Indici Ottimizzati

geohash → proximity lat,lon → bounding box timestamp → time queries fish_species → lookup nearest_water_name → water catch_photos.catch_id → join catch_tags → M:N sessions.start_time

🔀 Repository Pattern (DAL)

Tutte le query DB passano da repository.js. Le route non fanno mai query dirette. Il DAL espone funzioni tipizzate con parametri bound:

📐 Migration System

Dual-track: Lo schema base usa CREATE TABLE IF NOT EXISTS (per nuove installazioni). Le migration usano ALTER TABLE ADD COLUMN (per DB esistenti). Entrambi devono essere sincronizzati — ogni nuova colonna va aggiunta in entrambi.
06 — Sicurezza
Security Model
Security audit completato ad Aprile 2026 (commit a4d808b). Remediation in 7 fasi completata a Maggio 2026 (tag v1.1.0-security) — 135 test automatizzati coprono tutte le fix. Audit completo in SECURITY_AUDIT.md.
🔒
Autenticazione
API Key via custom header
  • Header: X-API-Key su tutti gli endpoint /api/*
  • Eccezione: GET /api/photos/* pubblico — i tag <img> non possono inviare header custom
  • Storage: Cloudflare Workers Secret in produzione (wrangler secret put API_KEY)
  • Admin: HTTP Basic Auth su /api/admin/* con timingSafeEqual
  • Cache: Cache-Control: private, no-store su tutte le risposte API autenticate
🛡️
Security Headers
Via hono/secure-headers middleware
  • CSP: default-src 'self' — zero CDN esterni. Admin UI usa nonce per-request su scriptSrc.
  • HSTS: max-age=31536000; includeSubDomains
  • CORS: Whitelist statica — NO wildcard, solo domini esatti di prod/staging/localhost
  • X-Frame: DENY · X-Content-Type: nosniff
  • Permissions-Policy: camera/geo self, 8 API sensibili bloccate
  • Vendor assets: SheetJS e font Inter self-hostati con SRI

✅ Validazioni Implementate

DoveCosaCome
catches.js POST/PUTCoordinate range, string lengthslat: -90..90, lon: -180..180, strings max 200/100/2000
catches.js photo uploadFile size, MIME type, magic bytesMax 10MB, whitelist jpeg/png/webp/heic, magic bytes via image-validation.js
admin.js importLimite righe, lat/lon per rigaMax 10.000 righe (413), range check per ogni record
admin.js restore fotoR2 key, size, magic bytesRegex ^catches/\d+/[A-Za-z0-9._-]+$, max 10MB, magic bytes
admin.js backup/restoreConferma esplicita?confirm=RESTORE obbligatorio; snapshot rollback in R2 prima dell'operazione
tags.js POSTName, color formatName required max 100 chars, color regex #RRGGBB
photos.js GETPath traversal, chiavi riservateBlock .., prefix check catches/, blocco _rollback/ (403)
repository.js updateColumn name injectionRegex /^[a-z_][a-z0-9_]*$/ + allowedFields whitelist
repository.js analyticsLIKE wildcard escape% e _ rimossi dall'input
zip.js restoreZIP malformati, path traversalFirma local header, bounds check, EOCD limitato a 64KB
geo.jsCrash provider esterniPromise.allSettled + try/catch → sempre 200, partial: true
app.js frontendXSS output encodingescapeHtml() con 5 entity su tutti gli output utente
worker.js globalError leak preventionapp.onError() + safeError() — mai stack trace al client
admin.js importTiming oracleConfronto admin password con timingSafeEqual — no timing leak
07 — REST API
Endpoint Reference
API RESTful completa con 24+ endpoint montati su Hono. Base URL: http://localhost:8787/api (dev) o https://geodata-fishing.*.workers.dev/api (prod).
EndpointMetodiAuthDescrizione
/api/healthGET🔑Health check con contatori (catches, sessions, photos, tags)
/api/statsGET🔑Statistiche aggregate (species count, locations count)
/api/catchesGET POST🔑Lista paginate (offset/limit) · Crea cattura dal GPS
/api/catches/:idGET PUT DEL🔑CRUD singola cattura con photos e tags
/api/catches/:id/photosGET POST🔑Lista + Upload foto (multipart o base64)
/api/catches/:id/tags/:tagIdPOST DEL🔑Associa/rimuovi tag da cattura
/api/catches/nearbyGET🔑Ricerca geospaziale per raggio (lat, lon, radius km)
/api/sessionsGET POST🔑Lista + Crea sessioni di pesca
/api/sessions/:idGET DEL🔑Dettaglio sessione con catture associate
/api/sessions/:id/endPUT🔑Chiudi sessione con note finali
/api/tagsGET POST🔑CRUD tag (name UNIQUE + color hex)
/api/tags/:idDEL🔑Elimina tag (CASCADE su associazioni)
/api/geo-dataGET🔑Dati geo-meteo live, integrato con location override
/api/analytics/species/:nameGET🔑AVG score/temp/pressure/wind per specie
/api/analytics/locationGET🔑Top 5 species + avg score per area geografica
/api/photos/*GET🌐Serve foto da R2 (pubblico — per tag <img>)
🔒 ADMIN — Basic Auth (admin:<ADMIN_PASSWORD>)
/api/adminGET🔐Pannello admin HTML (UI import/export/backup/luoghi/erase)
/api/admin/importPOST🔐Import bulk catture da Excel con coordinate default
/api/admin/exportGET🔐Export tutte le catture come JSON
/api/admin/backupGET🔐★ Genera e scarica backup completo ZIP (DB + foto R2)
/api/admin/backupPOST🔐★ Ripristina da backup ZIP — atomic erase + restore. Max 50MB
/api/admin/catchesGET🔐★ Records browser paginato — lista catture con filtri
/api/admin/catches/:idGET PUT DEL🔐★ Modifica/elimina singola cattura dall'admin
/api/admin/catches/:id/re-enrichPOST🔐★ Ri-arricchisce geo-meteo una cattura esistente
/api/admin/locationsGET POST🔐CRUD geo-fencing: lista + crea luogo (centro + raggio)
/api/admin/locations/:idPUT DEL🔐Aggiorna/elimina luogo configurato
/api/admin/erase-allPOST🔐Reset completo DB. Richiede { confirm: "ERASE ALL" }
08 — Frontend
Mobile-First SPA
Frontend Vanilla JS modulare senza framework, design system glassmorphic dark mode ottimizzato per l'uso in campo. Zero build step, PWA installabile.
📱
Stack Zero-Build Modulare
~2100 righe JS (6 moduli), ~2035 righe CSS
Vanilla JS (ES Modules) Zero Framework CSS Glassmorphic Leaflet Maps (self-hosted) Chart.js (self-hosted) Camera API (env: rear) Geolocation API (iOS-safe)
  • Routing: Hash router via `utils/router.js` con deep link (#/catch/{id}) e views modulari
  • State: Modulo `state.js` dedicato con subscribe patterns per gestire stato reattivamente tra views
  • PWA: Service Worker Workbox, manifest installabile, aggiornamento via toast persistente
  • Vendor assets: Leaflet, Chart.js, Workbox, Inter font — tutti self-hosted in web/js/vendor/ e web/css/vendor/. Zero CDN esterni a runtime
  • Offline & state persistence: localStorage namespaced sotto geodata.* via utils/storage.js (low-level) + utils/persistence.js (domain accessors con sanitizzazione). Persisti: capture draft completo (tutti gli input + tag, esclusi foto/override), filtri Galleria, filtri Stats, API key, angler name, geo permission, grafici custom
  • UX: Toast, skeleton loading, autocomplete, pinch-to-zoom foto, Charts custom
🧭
3 View Principali
SPA con dual navigation (mobile + desktop)
📸
Capture

Camera rear con preview live, cattura foto, form con autocomplete (21 esche, 29 specie), GPS lock, geo-data preview card, salvataggio con upload foto simultaneo. Upload da galleria con lettura automatica EXIF (GPS + data/ora) e dialog di conferma se i dati EXIF differiscono da quelli correnti. Override luogo/data tramite bottom-sheet unificato (geo-edit-sheet.js) con <dialog> nativo, swipe-to-dismiss, haptics e visualViewport tracking

📋
Gallery

Grid responsive con thumbnail da R2, ricerca per specie/luogo, filtro temporale (oggi/settimana). Tap → modal dettaglio con SVG score gauge, mappa Leaflet, 6 sezioni dati

📊
Stats

Contatori aggregati, top 5 specie, grafici avanzati (timeseries, scatter, doughnut, bar) via Chart.js wrapper, grafici personalizzabili dall'utente

🧩 Architettura Modulare Frontend

Moduli JS
FileRigheResponsabilità
app.js~110EntryPoint: init SPA, check intro video, event listener router globali
state.js, constants.js~200Definizione degli stati globali e query selectors/options costanti
views/*~600/eaModuli vista specifici: capture.js, gallery.js, stats.js separati per lazy logic
components/*varUI isolati: toast.js, modal.js, photo-viewer.js, autocomplete.js, exif-confirm.js, location-picker.js, geo-edit-sheet.js
api.js~156Client HTTP con X-API-Key, upload foto FormData/base64
chart-builder.js~340Chart.js wrapper: line, scatter, doughnut, bar. Config in localStorage
utils/router.js~76Hash route parsing (pure functions, zero DOM, testabile)
utils/geo.js~95Geolocation iOS-safe, permission tracking via localStorage
utils/image.js, helpers.js~100Compressione immagini e DOM helpers condivisi
utils/storage.js~90localStorage helpers namespaced (geodata.*), JSON/string round-trip, try/catch wrapped (private-mode/quota safe)
utils/persistence.js~95Domain accessors: loadCaptureDraft/save/clear, load/saveGalleryFilters, load/saveStatsFilters. Sanitizza shape al load (corrupt JSON → fallback)
Design System

Colori (CSS Vars)

  • BG: #0a0e1a
  • Card: rgba(15,23,42,.7) + blur
  • Accent: Cyan/Blue gradient
  • Score: Emerald→Red per range

Componenti

  • Toast (success/error/info)
  • Modal overlay collassabile
  • SVG ring gauge score
  • Skeleton loading
  • Bottom-sheet nativo (<dialog>) con swipe-to-dismiss

Responsive & Motion

  • Mobile-first <768px
  • Tablet 768-1199px
  • Desktop ≥1200px
  • Safe area insets + dvh/dvw
  • Material 3 emphasized easing tokens
  • prefers-reduced-motion globale

🗂️ API Client (api.js)

Pattern: Thin wrapper su fetch() con header X-API-Key iniettato automaticamente. Key letta da <meta name="api-key"> (SSR) o localStorage (fallback). Upload foto supporta sia FormData (multipart) che JSON (base64).
09 — Routing
Hash Router — URL Condivisibili
L'app usa hash routing per URL condivisibili e deep link. Il fragment hash (#...) non viene mai inviato al server — zero modifiche backend, massima sicurezza.
🔗
Route Supportate
Parsing puro in utils/router.js (~76 righe)
HashRisultato
#/captureVista Cattura
#/galleryVista Galleria
#/statsVista Statistiche
#/catch/{id}Deep link → gallery + modal dettaglio cattura
(vuoto o invalido)Fallback sicuro → vista Cattura
🏗️
Architettura Router
Separazione logica pura / DOM
1
router.js (pure functions)

Logica di parsing: parseRoute(hash), catchHash(id), viewHash(view). Zero dipendenze browser — testabile con bun test.

2
app.js (thin wrapper)

parseHash() chiama parseRoute(location.hash). setHash() usa history.replaceState — non inquina la history. init() gestisce route iniziale + listener hashchange.

3
Share & Deep Link

Share button include location.origin + /#/catch/{id} via navigator.share(). Deep link carica gallery, poi apre modal. Cattura inesistente → toast errore + fallback.

🔒 Sicurezza Router

🔑
API Key mai nell'URL

Il fragment hash non viene inviato al server — la key resta nel header HTTP X-API-Key

✅
ID Validato

Regex strict /^catch\/(\d+)$/, range 1..2³¹-1 (SQLite INTEGER safe)

🛡️
Whitelist Viste

Solo capture, gallery, stats accettati. Qualsiasi hash invalido → fallback sicuro a capture

⚠️ Gotcha Router

10 — PWA
Progressive Web App & Service Worker
Nautilus è una PWA installabile con Service Worker Workbox v7.4.0. Caching multi-strategia, aggiornamento automatico, e installazione nativa su iOS/Android/Desktop.
⚡
Service Worker (Workbox)
sw.js — 4 strategie di caching
StrategiaTargetTTL / Cap
PrecacheApp shell: HTML, CSS, JS, manifest, icone, font, vendor libs (tutto self-hosted)Versioned (APP_VERSION)
CacheFirstFoto da R2 (/api/photos/*)7gg / 100 foto
NetworkOnlyChiamate API (/api/* escluse foto)Mai cachate — dati live
Dopo il commit eb2ebb0, Leaflet, Chart.js, Workbox e il font Inter sono tutti self-hosted in web/js/vendor/ e web/assets/fonts/. La strategia StaleWhileRevalidate per Google Fonts è stata rimossa — zero dipendenze CDN a runtime.
🔄
Aggiornamento Automatico
scripts/bump-sw.mjs
1
Version Bump

bump-sw.mjs genera APP_VERSION = 'YYYY.MM.DD.HHmmss' e sovrascrive la costante in sw.js. Ogni entry nel precache usa questa versione come revision.

2
Deploy

npm run deploy = bump-sw.mjs + wrangler deploy. Il browser rileva il diff di byte nel SW e forza l'installazione della nuova versione.

3
Client Notify

skipWaiting() + clients.claim() attivano il nuovo SW immediatamente. Evento controllerchange → toast persistente "🔄 Aggiornamento disponibile" con bottone Aggiorna. Il reload avviene solo su click utente — nessun interrupt in uso.

📲 Installazione PWA

📱
iOS Safari
Condividi → Aggiungi alla Schermata Home
  • Rilevamento: User-Agent iPhone/iPod + iPad con maxTouchPoints ≥ 5 e pointer: coarse
  • Esclusione macOS: MacIntel senza touch coarse = desktop → bottone nascosto
  • Guida: Toast interattivo con istruzioni passo-passo (auto-dismiss 8s)
  • Meta tags: apple-mobile-web-app-capable, apple-touch-icon, status bar black-translucent
🤖
Android / Desktop
beforeinstallprompt API
  • Trigger: Evento beforeinstallprompt → mostra bottone "Installa" nel header
  • Prompt nativo: Click → deferredPrompt.prompt() → dialog installazione OS
  • Post-install: Evento appinstalled → bottone nascosto automaticamente
  • Standalone check: Se già installata (display-mode: standalone), bottone mai visibile

📋 Web App Manifest

Identità

  • Nome: Nautilus Carpfishing
  • Short: Nautilus
  • Display: standalone
  • Orientation: portrait-primary

Icone

  • icon-512.png (512×512)
  • icon-192.png (192×192)
  • apple-touch-icon.png (180×180)
  • icon-32.png, icon-16.png

Theme

  • Background: #060a14
  • Theme: #060a14
  • Categories: sports, lifestyle
  • Lang: it
11 — Testing
Test Suite & Coverage
Suite hardened con 904 test e 2229 asserzioni su 47 file. Copertura 94.28% funzioni e 95.72% linee. Tre fasi: backend lib, repository/routes integration, frontend utilities. Esecuzione ~7s con Bun test runner.
✅ 904 test 94.28% Funzioni 95.72% Linee 2229 Assertions 47 file test 0 fail · 0 skip
File TestModulo TestatoCosa Verifica
FASE 1 — BACKEND LIB (UNIT TEST)
scientific-geomagnetic.test.jsscientific.js (Kp)NOAA legacy/new format parsing, Kp impact levels, HTTP/network errors, empty arrays
scientific.test.jsscientific.jsWater temp estimation, twilight bonus, temp delta 24h, edge cases
weather.test.jsweather.jsHistorical weather parsing, pressure trend (6h), HTTP errors, sparse data
weather-manager.test.jsweather-manager.jsWaterfall fallback open-meteo → yr-no, all providers fail → throws
weather-providers.test.jsopen-meteo.js, yr-no.jsResponse parsing, field mapping, fallback to Yr.no, timeout handling
location.test.jslocation.jsNominatim parsing, tides, Overpass mirror fallback, dams metadata, sorting
geo-data.test.jsgeo-data.jsCurrent + historical paths, data_quality tracking, partial/total API failure
cache.test.jscache.jsRadial lookup, TTL expiry, FIFO eviction, historical cache, distance threshold
water-level.test.jswater-level.jsOAuth2 flow mock, station filtering (hwl), multi-sensor, Haversine, no-hwl fallback
fishing-score.test.jsfishing-score.jsTutti i fattori singoli e combinati, edge cases (tutti null, tutti ottimali), range 0-100
lunar.test.jslunar.js8 fasi lunari, illumination, solunar periods, day rating, timing precision
utils.test.jsutils.jsCardinal conversion, geohash, haversine, weather codes, escapeHtml
FASE 2 — REPOSITORY & ROUTES (INTEGRATION)
repository-crud.test.jsrepository.js (DAL)Full CRUD: storeCatch (55 params), getCatch, updateCatch, photos, tags, sessions, locations, admin, analytics
repository-analytics.test.jsrepository.js (analytics)Species analytics queries, location stats, aggregation functions
worker.test.jsworker.js + routesIntegration test: mock D1/R2, auth guard, CRUD, photo upload, validation, error handling
routes.test.jsAll routes (62 test)Catches PUT/DELETE, photo upload (base64/multipart), admin CRUD, analytics, sessions, tags, CORS
routes-deep.test.jsUncovered pathsCatches POST create E2E, geo matched_location, admin enriched import, enrich, location override
catches-filters.test.jscatches.js (filters)Gallery filter queries, angler/location/date filters, pagination
analytics-api.test.jsanalytics.js routeTimeseries, distribution endpoint, pagination, error handling
admin-api.test.jsadmin.jsAuth guard (Basic Auth), import validation, export, error handling
admin-locations.test.jsadmin.js + repository.jsLocations CRUD, validation water_type, findMatchingLocation, erase all
location-override.test.jscatches.js + repository.jsHaversine sanity, geo-fencing match/miss, GET /api/catches override E2E
app-syntax.test.jsadmin-ui.jsTemplate literal syntax validation, escape characters check
FASE 3 — FRONTEND (MOCK DOM)
helpers.test.jsutils/helpers.jsgetScoreClass/Color boundaries, formatDate/DateTime, escapeHtml XSS payload
frontend-state.test.jsstate.jsDefault values, state shape integrity, mutability
frontend-constants.test.jsconstants.jsBAITS/SPECIES/BAIT_BRANDS: no duplicates, expected entries, non-empty strings
frontend-geo.test.jsutils/geo.jsformatCoords, isIOS (navigator mock), hasGrantedGeolocation (localStorage), getPosition
frontend-image.test.jsutils/image.jsdataURLtoBlob: JPEG/PNG/WebP, binary preservation, edge cases
chart-builder.test.jschart-builder.jsCRUD chart config, validation, all 4 renderers (mock DOM/Chart.js), lifecycle, horizontal bar
router.test.jsutils/router.jsHash parsing, catch ID validation (range, XSS), view whitelist, fallback
persistence.test.jsutils/storage.js + utils/persistence.jslocalStorage helpers + domain accessors (capture draft, gallery/stats filters): round-trip, defaults, sanitize shape, corrupt JSON fallback, namespacing

🧪 Strategia di Testing (3 Fasi)

Mock Pattern
  • D1: Mock completo con prepare().bind().run()/first()/all() + prepareFn configurabile
  • R2: Mock put(), get() e delete() con Map in-memory
  • Fetch: globalThis.fetch mockato per ogni provider API (7 provider)
  • DOM: document.getElementById stub per Chart.js rendering
  • Navigator: Mock navigator.userAgent, platform, geolocation per iOS detection
  • localStorage: Map-based mock per chart configs e geo permissions
  • AbortController: Test timeout con controller.abort()
Comandi
# Run all tests bun test # With coverage report bun test --coverage # Single file bun test tests/fishing-score.test.js # Watch mode bun test --watch

📊 Copertura per Modulo

Backend — 100% linee (18 moduli)
geo-data.js ✓ open-meteo.js ✓ utils.js ✓ admin-ui.js ✓ analytics.js ✓ catches.js 99% geo.js ✓ tags.js ✓ worker.js ✓ location.js ✓ scientific.js ✓ weather.js ✓ yr-no.js ✓ sessions.js ✓ water-level.js 99% repository.js 95% admin.js 94% cache.js 89%
Frontend — 100% linee (7 moduli)
constants.js ✓ state.js ✓ helpers.js ✓ router.js ✓ chart-builder.js ✓ geo.js 96% image.js 18%

image.js richiede Canvas/Image browser API — non testabile in bun. Escludendolo, coverage >97%.

12 — Deploy
Workflow di Deploy
Un singolo comando deploya API, database, storage e frontend. Il Service Worker viene versionato automaticamente. Tutto gestito da Wrangler.
1
Setup Secrets

wrangler secret put API_KEY — imposta l'API key nel runtime produzione. Mai in codice.

2
Init Database

wrangler d1 execute geodata-fishing --file=src/db/schema.sql — crea le tabelle D1.

3
Run Migrations

wrangler d1 execute geodata-fishing --file=src/db/migrations/003_water_levels.sql --remote · 004_bait_presentation.sql · 005_locations.sql · 006_dedup_catches.sql · 007_fix_column_scramble.sql — aggiunge colonne, tabelle e corregge eventuali scramble. ⚠️ 006 usa colonne esplicite nel INSERT…SELECT (mai SELECT * tra tabelle che possono divergere per ALTER TABLE).

4
Deploy

npm run deploy — esegue bump-sw.mjs (versiona il Service Worker) poi wrangler deploy. Worker, static assets e bindings D1/R2 in un colpo solo.

⚙️ wrangler.toml

name = "geodata-fishing" main = "src/worker.js" compatibility_date = "2025-12-01" [assets] directory = "./web" [[d1_databases]] binding = "DB" database_name = "geodata-fishing" database_id = "<uuid>" [[r2_buckets]] binding = "PHOTOS" bucket_name = "geodata-photos"
Perché Cloudflare? Deploy istantaneo con un singolo comando. Zero server, zero scaling manuale, zero cold start. Database SQLite co-locato col codice per latenza minima. Object storage senza costi di egress. Frontend servito dalla stessa infrastruttura — tutto in un unico deploy, un solo wrangler.toml.