How p4za/alagalert works
Project Type and Purpose
• AlagAlert is a distributed full-stack application for flood-risk forecasting in Brazilian cities.
• It comprises a Flutter mobile app (UI layer) and a FastAPI backend (API layer) that aggregates meteorological and geocoding data, applies a risk-calculation engine, and exposes endpoints.
File-Structure Analysis
• Top-level:
• backend/ – FastAPI service (app/, data/, tools/)
• mobile/ – Flutter app (lib/, assets/, web/, test/)
• Patterns & layers:
• backend/app/main.py defines API controllers → services/ modules implement integrations (Open-Meteo, Nominatim, IBGE, mock risk areas) → utils/risk_engine.py computes risk
• backend/data holds static IBGE geoJSON for municipalities and UFs
• mobile/lib organized by models (data contracts), services (API clients), screens (UI), widgets, theme
• Config & deployment:
• backend/.env.example, requirements.txt, uvicorn startup
• mobile/pubspec.yaml, analysis_options.yaml, platform-specific build scripts
README Insights
• Core components: Flutter app → calls intermediate API → which in turn calls external services (Open-Meteo for weather, Nominatim for geocode, OpenStreetMap for tiles).
• Exposed endpoints: /geocode, /geocode-states, /risk/by-city, /risk/areas.
• Caching (cachetools), rate limiting (slowapi), asynchronous HTTP (httpx).
• Detailed list of improvements shows modularization of WeatherService, RiskEngine, EnhancedMapScreen with dynamic polygons.
• Mobile App (Flutter)
• API Gateway / FastAPI Service
• Risk Engine Module (within backend)
• Data Store (static IBGE geoJSON)
• External Services: Open-Meteo, Nominatim, OpenStreetMap Tiles
1. User taps UI → Flutter screens call ApiService → HTTP request to FastAPI endpoints
2. FastAPI endpoint handlers route calls to service layer:
– geocode service → Nominatim → returns city/UF coordinates
– weather client → Open-Meteo → returns forecast data
– regions service → IBGE geoJSON files → returns municipal boundaries
– risk_areas service → mock risk polygons
3. RiskEngine aggregates data (weather + geocode + regions) and computes risk score or GeoJSON polygons
4. FastAPI returns JSON or GeoJSON to mobile
5. Flutter map widget consumes GeoJSON and OSM tile server for map rendering
c. Architectural Patterns / Principles:
– Layered architecture: Presentation (mobile), API/Controller, Service/Integration, Business Logic (risk_engine), Data Layer (static files)
– Asynchronous I/O in backend (httpx, Uvicorn) for scalable external calls
– Caching layer for performance (cachetools TTL)
– Separation of concerns: each service module has a single integration responsibility
d. Key Technologies:
– Frontend: Flutter, Dart, flutter_map, flutter_typeahead
– Backend: FastAPI, Uvicorn, Pydantic, httpx, cachetools, slowapi
– Data: IBGE geojson, static JSON files
– External APIs: Open-Meteo, Nominatim, OpenStreetMap