# p4za/alagalert architecture

> Architecture diagram of the GitHub repository p4za/alagalert, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/p4za/alagalert
- Repository: https://github.com/p4za/alagalert

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Mobile App (Flutter)"
        direction TB
        Entry["main.dart"]:::client
        subgraph Screens
            direction TB
            ScreensNode["City Picker, Map, Risk Results, Settings, Favorites"]:::client
        end
        subgraph Widgets
            direction TB
            WidgetsNode["Location Cards, Metric Chips, etc."]:::client
        end
        subgraph Services_Client
            direction TB
            APIService["ApiService"]:::client
            GeoService["GeocodeService"]:::client
            IBGEService["IBGEService"]:::client
            WeatherClientMobile["WeatherService"]:::client
        end
        subgraph Models
            direction TB
            LocationModel["location.dart"]:::client
            RegionModel["region.dart"]:::client
            WeatherModel["weather.dart"]:::client
            RiskModel["risk.dart"]:::client
        end
        subgraph Theme
            direction TB
            AppTheme["app_theme.dart"]:::client
            Levels["levels.dart"]:::client
        end
    end

    subgraph "Backend Service (FastAPI)"
        direction TB
        API["main.py"]:::backend
        Schemas["schemas.py"]:::backend
        subgraph Services_Backend
            direction TB
            GeocodeSvc["geocode.py"]:::backend
            WeatherSvc["weather_client.py"]:::backend
            NeighborhoodWeather["neighborhood_weather.py"]:::backend
            RegionsSvc["regions.py"]:::backend
            RiskAreasSvc["risk_areas.py"]:::backend
            BrasilAberto["brasil_aberto.py"]:::backend
        end
        RiskEngine["risk_engine.py"]:::backend
    end

    DataStore["Static IBGE GeoJSON"]:::datastore

    subgraph "Developer Tools"
        direction TB
        AddCities["add_cities.py"]:::tools
    end

    ExternalNominatim["Nominatim API"]:::external
    ExternalWeather["Open-Meteo API"]:::external
    ExternalTiles["OpenStreetMap Tiles"]:::external

    Entry -->|launch| APIService
    APIService -->|"HTTP requests"| API
    API -->|"uses schemas"| Schemas

    API -->|"GET /geocode"| GeocodeSvc
    GeocodeSvc -->|"requests"| ExternalNominatim

    API -->|"GET /risk/by-city"| RiskEngine
    API -->|"GET /risk/areas"| RiskAreasSvc
    RiskAreasSvc --> RiskEngine

    API -->|"GET /geocode-states"| RegionsSvc
    RegionsSvc --> DataStore

    API -->|"GET /weather"| NeighborhoodWeather
    NeighborhoodWeather --> WeatherSvc
    WeatherSvc -->|"requests"| ExternalWeather

    RiskEngine --> GeocodeSvc
    RiskEngine --> NeighborhoodWeather
    RiskEngine --> RegionsSvc

    API -->|"response JSON/GeoJSON"| APIService
    APIService --> ScreensNode
    ScreensNode --> WidgetsNode
    WidgetsNode --> ExternalTiles

    classDef client fill:#cce5ff,stroke:#4d94ff,stroke-width:2px
    classDef backend fill:#d6f5d6,stroke:#33cc33,stroke-width:2px
    classDef external fill:#ffe0b3,stroke:#ff9933,stroke-width:2px
    classDef datastore fill:#f2f2f2,stroke:#bfbfbf,stroke-width:2px
    classDef tools fill:#f9e6ff,stroke:#cc66ff,stroke-width:2px

    click Entry "https://github.com/p4za/alagalert/blob/main/mobile/lib/main.dart"
    click ScreensNode "https://github.com/p4za/alagalert/tree/main/mobile/lib/screens"
    click WidgetsNode "https://github.com/p4za/alagalert/tree/main/mobile/lib/widgets"
    click APIService "https://github.com/p4za/alagalert/blob/main/mobile/lib/services/api_service.dart"
    click GeoService "https://github.com/p4za/alagalert/blob/main/mobile/lib/services/geocode_service.dart"
    click IBGEService "https://github.com/p4za/alagalert/blob/main/mobile/lib/services/ibge_service.dart"
    click WeatherClientMobile "https://github.com/p4za/alagalert/blob/main/mobile/lib/services/weather_service.dart"
    click LocationModel "https://github.com/p4za/alagalert/blob/main/mobile/lib/models/location.dart"
    click RegionModel "https://github.com/p4za/alagalert/blob/main/mobile/lib/models/region.dart"
    click WeatherModel "https://github.com/p4za/alagalert/blob/main/mobile/lib/models/weather.dart"
    click RiskModel "https://github.com/p4za/alagalert/blob/main/mobile/lib/models/risk.dart"
    click AppTheme "https://github.com/p4za/alagalert/blob/main/mobile/lib/theme/app_theme.dart"
    click Levels "https://github.com/p4za/alagalert/blob/main/mobile/lib/theme/levels.dart"

    click API "https://github.com/p4za/alagalert/blob/main/backend/app/main.py"
    click Schemas "https://github.com/p4za/alagalert/blob/main/backend/app/schemas.py"
    click GeocodeSvc "https://github.com/p4za/alagalert/blob/main/backend/app/services/geocode.py"
    click WeatherSvc "https://github.com/p4za/alagalert/blob/main/backend/app/services/weather_client.py"
    click NeighborhoodWeather "https://github.com/p4za/alagalert/blob/main/backend/app/services/neighborhood_weather.py"
    click RegionsSvc "https://github.com/p4za/alagalert/blob/main/backend/app/services/regions.py"
    click RiskAreasSvc "https://github.com/p4za/alagalert/blob/main/backend/app/services/risk_areas.py"
    click BrasilAberto "https://github.com/p4za/alagalert/blob/main/backend/app/services/brasil_aberto.py"
    click RiskEngine "https://github.com/p4za/alagalert/blob/main/backend/app/utils/risk_engine.py"
    click DataStore "https://github.com/p4za/alagalert/tree/main/backend/data/ibge"
    click AddCities "https://github.com/p4za/alagalert/blob/main/backend/tools/add_cities.py"
```
