Documentazione HapGree

Obiettivo del portale

Questo portale raccoglie la documentazione tecnica dell'applicazione mobile HapGree, client Flutter sviluppato per il monitoraggio dell'impronta di CO2 personale, la gamification tramite challenge e gruppi di utenti, e la compensazione delle emissioni di carbonio.

All'interno sono descritte l'architettura applicativa, i flussi di business chiave, le configurazioni per i diversi ambienti e la mappatura dei requisiti funzionali di progetto (da RF1 a RF95).

Panorama del sistema

L'applicazione mobile Flutter implementa le seguenti funzionalità principali:

• autentica l'utente interfacciandosi con il nostro backend REST proprietario;
• raccoglie e valida gli input dell'utente su mobilità, energia, alimentazione e attività fisica;
• delega al backend il calcolo canonico delle emissioni e la generazione delle dashboard aggregate;
• si integra con servizi terzi essenziali: Firebase, Google Maps Platform, Health Connect / Apple Health, PayPal e OpenFoodFacts;
• struttura l'interfaccia utente secondo il pattern architetturale MVVM, con Provider per lo state management e go_router per la navigazione dichiarativa.

Nota di integrazione: Il client mobile non accede direttamente al database. Tutte le entità e i dati descritti nella documentazione rappresentano il modello dati logico scambiato tramite i DTO OpenAPI e le chiamate REST. Schemi relazionali, migrazioni e job batch asincroni sono gestiti interamente dai servizi di backend.

Architettura ad alto livello

flowchart TD
    A[Flutter Mobile App] --> B[Routing go_router]
    A --> C[Provider + MVVM]
    C --> D[ViewModel]
    D --> E[HapGreeApiContainer]
    E --> F[REST API Backend HapGree]

    A --> G[Firebase Core/Auth/Messaging]
    A --> H[Health Connect / Apple Health]
    A --> I[Google Maps / Places / Geocoding]
    A --> J[Google ML Kit OCR]
    A --> K[OpenFoodFacts]
    A --> L[PayPal via backend]

    A --> M[flutter_background_service]
    M --> N[Geolocator + Activity Recognition]
    N --> O[TrackingStateMachine + GpsFilterUtils]
    O --> P[SharedPreferences driving_history]
    P --> F

    F --> Q[Dashboard, Emissioni, Challenge, Gruppi, FAQ, Tips]
    Q --> A

Stack tecnologico di riferimento

Di seguito sono elencate le tecnologie, i vincoli di SDK e le librerie principali adottate nel progetto:

Componente	Versione / Configurazione
Versione app Flutter	0.7.11+24
Dart SDK constraint	^3.5.4
Canale Flutter	stable
Android minSdk	31
iOS deployment target	15.5
State management	provider ^6.1.2
Routing	go_router ^14.8.0
Firebase Core	^3.8.0
Firebase Auth	^5.3.3
Firebase Messaging	^15.2.10
Cloud Firestore	^5.5.1
Secure storage	flutter_secure_storage ^9.2.4
Local preferences	shared_preferences ^2.5.3
Health integration	health ^12.0.1
Geolocation	geolocator ^14.0.0
Background execution	flutter_background_service ^5.1.0
Local notifications	flutter_local_notifications ^19.2.1
Maps SDK	google_maps_flutter ^2.12.1
Places autocomplete	google_places_flutter ^2.0.5
Geocoding	google_geocoding_api ^1.0.1
OCR	google_mlkit_text_recognition ^0.15.0
Barcode / QR	mobile_scanner ^6.0.7
Food lookup	openfoodfacts ^3.21.0
Decimal math	decimal ^3.0.2
Charting	fl_chart ^0.70.2
HTTP client API generato	hapgree_client (sotto libs/hapgree-client)
Shared result/error wrapper	result_and_error (sotto libs/resultAndError)

Architettura software applicativa

Pattern e organizzazione del codice

• MVVM: abbiamo separato le viste dichiarative in lib/view, i ViewModel in lib/viewModel, e i modelli/entità in lib/model e lib/entity.
• Provider graph centralizzato: configurato in lib/main.dart, gestisce l'iniezione del container API, dello stato di autenticazione, del tracking e delle logiche di compensazione.
• Client OpenAPI generato: HapGreeApiContainer espone le istanze delle API specializzate (AuthApi, ViaggiApi, EnergyApi, CompensazioneApi, ecc.), generate automaticamente a partire dai contratti OpenAPI.
• Routing modulare: le rotte sono suddivise per dominio funzionale in lib/Routing/Routes/*.
• Persistenza locale mirata: usiamo FlutterSecureStorage per i token di sessione e SharedPreferences per le preferenze utente, lo stato dell'onboarding e la coda temporanea dei viaggi tracciati in background.

Gestione e calcolo della CO2

Per garantire coerenza tra piattaforme e storicizzazioni, il calcolo delle emissioni di CO2 è centralizzato sul backend. L'app mobile raccoglie e invia i dati operativi:

• viaggi e spostamenti (CreateTravel);
• consumi energetici e bollette;
• alimenti registrati (manualmente, via barcode o scontrino);
• attività fisica sincronizzata;
• richieste e transazioni di compensazione.

Il backend restituisce al client i dati già aggregati (giornalieri, settimanali, mensili, annuali), i breakdown di categoria, i progressi delle challenge e le classifiche.

Servizi e integrazioni esterne

Servizio	Utilizzo nell'applicazione
Firebase	Bootstrap dell'app, autenticazione e ricezione notifiche push (FCM)
Google Maps Platform	Visualizzazione mappe, coordinate geografiche e percorsi
Google Places	Autocomplete e ricerca di punti di interesse/indirizzi
Google Geocoding	Risoluzione inversa e diretta di coordinate/indirizzi
Google ML Kit	Riconoscimento testo OCR per scontrini alimentari e bollette
Health Connect (Android)	Lettura sincronizzata di passi e distanza
Apple Health (iOS)	Lettura sincronizzata di passi e distanza
OpenFoodFacts	Recupero metadati e informazioni nutrizionali/ecologiche dei prodotti alimentari
PayPal	Gestione transazioni di compensazione mediate dal backend
Docker & Tooling OpenAPI	Rigenerazione automatica del client Dart dalle specifiche OpenAPI

Ambienti di esecuzione

Il progetto supporta tre ambienti:

• prod: collegato all'ambiente di produzione (api.hapgree.com) e al relativo progetto Firebase di produzione.
• dev: collegato all'ambiente di collaudo/sviluppo (api-testing.hapgree.com) e a Firebase di sviluppo.
• local: permette di testare l'app contro un'istanza locale del backend (configurata in lib/Configuration.dart), riutilizzando i servizi Firebase di sviluppo.

Note di sviluppo e manutenzione

• La persistenza definitiva e la logica di calcolo risiedono sul backend; il client si occupa della raccolta dati e della user experience.
• L'ambiente local è progettato per semplificare lo sviluppo mobile locale puntando al backend su macchina host (es. 10.0.2.2:3000 su Android Emulator).
• La generazione del client API può essere rieseguita tramite gli script dedicati in Scripts/DartCodeGeneration/ ogni volta che le specifiche OpenAPI vengono aggiornate.