# moussaabbadla/algeria-fire-map architecture

> Architecture diagram of the GitHub repository moussaabbadla/algeria-fire-map, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/moussaabbadla/algeria-fire-map
- Repository: https://github.com/moussaabbadla/algeria-fire-map

## Overview

Algeria Fire Map presents current and historical wildfire activity, fire danger, exposed communities, forecasts, and restoration priorities through a bilingual map-first web app. The principal workflow is a visitor exploring a map or statistics view, which requests data from the FastAPI service; the backend serves live FIRMS detections and persisted or computed products. Scheduled ingestion enriches and clusters detections for downstream views. Edges reflect README documentation and shown source references/calls; unsampled UI and domain implementations limit finer-grained flow claims.

Main entry points: [`services/api/app/main.py`](https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/main.py) (FastAPI service), [`services/api/app/ingest.py`](https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/ingest.py) (FIRMS ingestion), [`services/api/app/db.py`](https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/db.py) (Postgres / PostGIS), [`apps/web/lib/api.ts`](https://github.com/moussaabbadla/algeria-fire-map/blob/main/apps/web/lib/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_fire_ui["Fire dashboard<br/>[FireDashboard.tsx]"]
  node_fire_map["Fire map<br/>[FireMap.tsx]"]
  node_timeline["Timeline replay"]
  node_at_risk_ui["At-risk communities<br/>[AtRiskPanel.tsx]"]
  node_risk_ui["FWI risk view<br/>[RiskPanel.tsx]"]
  node_restore_ui["Restoration view"]
  node_stats_ui["Statistics views<br/>[StatsView.tsx]"]
  node_charts["Stats charts<br/>[statsCharts.tsx]"]
  node_choropleth["Wilaya choropleth"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["API products"]
  node_api_service["FastAPI service<br/>[main.py]"]
  node_fire_routes["Fire and event APIs<br/>[fires.py]"]
  node_at_risk_route["At-risk API<br/>[at_risk.py]"]
  node_risk_route["Weather risk API<br/>[risk.py]"]
  node_restore_route["Restoration API<br/>[restoration.py]"]
  node_stats_route["Statistics API<br/>[stats.py]"]
  node_forecast_route["Forecast API<br/>[forecast.py]"]
end

subgraph group_lifecycle["Data lifecycle"]
  node_ingest["FIRMS ingestion<br/>[ingest.py]"]
  node_firms["FIRMS fetch<br/>[firms.py]"]
  node_clustering["Incident clustering<br/>[cluster.py]"]
  node_landcover["Burn-scar land cover<br/>[landcover.py]"]
  node_severity["Burn severity<br/>[severity.py]"]
  node_prediction["Grid risk prediction<br/>[predict.py]"]
  node_places["Place risk analysis<br/>[places.py]"]
  node_stats_logic["Statistics aggregation<br/>[stats.py]"]
end

subgraph group_state["State and providers"]
  node_weather["Weather provider<br/>[weather.py]"]
  node_fwi["FWI calculation<br/>[fwi.py]"]
  node_database[("Postgres / PostGIS<br/>[db.py]")]
  node_cache["Response cache<br/>[cache.py]"]
end

node_visitor(("Map visitor"))
node_firms_service["NASA FIRMS"]
node_meteo_service["Open-Meteo"]
node_gee_service["Earth Engine"]

node_visitor -->|"explores"| node_fire_ui
node_fire_ui -->|"requests data"| node_api_client
node_fire_ui -.->|"displays"| node_fire_map
node_fire_ui -.->|"offers replay"| node_timeline
node_visitor -->|"views exposure"| node_at_risk_ui
node_at_risk_ui -->|"requests data"| node_api_client
node_visitor -->|"views danger"| node_risk_ui
node_risk_ui -->|"requests data"| node_api_client
node_visitor -->|"views recovery"| node_restore_ui
node_restore_ui -->|"requests data"| node_api_client
node_visitor -->|"explores history"| node_stats_ui
node_stats_ui -->|"renders"| node_charts
node_stats_ui -->|"renders"| node_choropleth
node_stats_ui -.->|"requests data"| node_api_client
node_api_client -->|"calls HTTPS API"| node_api_service
node_api_service -->|"registers routes"| node_fire_routes
node_api_service -->|"registers routes"| node_at_risk_route
node_api_service -->|"registers routes"| node_risk_route
node_api_service -->|"registers routes"| node_restore_route
node_api_service -->|"registers routes"| node_stats_route
node_api_service -->|"registers routes"| node_forecast_route
node_api_service -->|"starts scheduler"| node_ingest
node_fire_routes -->|"fetches detections"| node_firms
node_fire_routes -->|"reads cache"| node_cache
node_at_risk_route -->|"queries communities"| node_places
node_at_risk_route -->|"reads cache"| node_cache
node_risk_route -->|"fetches weather"| node_weather
node_risk_route -->|"computes index"| node_fwi
node_risk_route -->|"reads and writes"| node_cache
node_restore_route -->|"reads cache"| node_cache
node_restore_route -.->|"serves scar data"| node_database
node_stats_route -->|"queries summaries"| node_stats_logic
node_forecast_route -->|"reads predictions"| node_database
node_forecast_route -->|"reads and writes"| node_cache
node_ingest -->|"fetches fires"| node_firms
node_ingest -->|"upserts detections"| node_database
node_ingest -->|"reclusters events"| node_clustering
node_ingest -->|"refreshes rollups"| node_stats_logic
node_ingest -->|"schedules enrichment"| node_landcover
node_ingest -->|"schedules enrichment"| node_severity
node_ingest -->|"schedules scoring"| node_prediction
node_firms -->|"fetches satellite data"| node_firms_service
node_clustering -->|"updates incidents"| node_database
node_landcover -->|"enriches scar records"| node_database
node_landcover -.->|"queries land cover"| node_gee_service
node_severity -->|"stores severity"| node_database
node_prediction -->|"writes cell scores"| node_database
node_places -->|"queries places and fires"| node_database

click node_fire_ui "https://github.com/moussaabbadla/algeria-fire-map/blob/main/apps/web/components/FireDashboard.tsx"
click node_fire_map "https://github.com/moussaabbadla/algeria-fire-map/blob/main/apps/web/components/FireMap.tsx"
click node_timeline "https://github.com/moussaabbadla/algeria-fire-map/blob/main/apps/web/components/TimelineScrubber.tsx"
click node_at_risk_ui "https://github.com/moussaabbadla/algeria-fire-map/blob/main/apps/web/components/AtRiskPanel.tsx"
click node_risk_ui "https://github.com/moussaabbadla/algeria-fire-map/blob/main/apps/web/components/RiskPanel.tsx"
click node_restore_ui "https://github.com/moussaabbadla/algeria-fire-map/blob/main/apps/web/components/RestoreDashboard.tsx"
click node_stats_ui "https://github.com/moussaabbadla/algeria-fire-map/blob/main/apps/web/components/StatsView.tsx"
click node_charts "https://github.com/moussaabbadla/algeria-fire-map/blob/main/apps/web/components/statsCharts.tsx"
click node_choropleth "https://github.com/moussaabbadla/algeria-fire-map/blob/main/apps/web/components/NationalChoropleth.tsx"
click node_api_client "https://github.com/moussaabbadla/algeria-fire-map/blob/main/apps/web/lib/api.ts"
click node_api_service "https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/main.py"
click node_fire_routes "https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/routers/fires.py"
click node_at_risk_route "https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/routers/at_risk.py"
click node_risk_route "https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/routers/risk.py"
click node_restore_route "https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/routers/restoration.py"
click node_stats_route "https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/routers/stats.py"
click node_forecast_route "https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/routers/forecast.py"
click node_ingest "https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/ingest.py"
click node_firms "https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/firms.py"
click node_clustering "https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/cluster.py"
click node_landcover "https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/landcover.py"
click node_severity "https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/severity.py"
click node_prediction "https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/predict.py"
click node_places "https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/places.py"
click node_stats_logic "https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/stats.py"
click node_weather "https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/weather.py"
click node_fwi "https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/fwi.py"
click node_database "https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/db.py"
click node_cache "https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/cache.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_fire_ui,node_fire_map,node_timeline,node_at_risk_ui,node_risk_ui,node_restore_ui,node_stats_ui,node_charts,node_choropleth,node_api_client toneBlue
class node_api_service,node_fire_routes,node_at_risk_route,node_risk_route,node_restore_route,node_stats_route,node_forecast_route toneAmber
class node_ingest,node_firms,node_clustering,node_landcover,node_severity,node_prediction,node_places,node_stats_logic toneMint
class node_weather,node_fwi,node_database,node_cache toneRose
class node_visitor,node_firms_service,node_meteo_service,node_gee_service toneIndigo
```

## Components

### Web experience

- [Fire dashboard](https://github.com/moussaabbadla/algeria-fire-map/blob/main/apps/web/components/FireDashboard.tsx): `apps/web/components/FireDashboard.tsx`
- [Fire map](https://github.com/moussaabbadla/algeria-fire-map/blob/main/apps/web/components/FireMap.tsx): `apps/web/components/FireMap.tsx`
- [Timeline replay](https://github.com/moussaabbadla/algeria-fire-map/blob/main/apps/web/components/TimelineScrubber.tsx): `apps/web/components/TimelineScrubber.tsx`
- [At-risk communities](https://github.com/moussaabbadla/algeria-fire-map/blob/main/apps/web/components/AtRiskPanel.tsx): `apps/web/components/AtRiskPanel.tsx`
- [FWI risk view](https://github.com/moussaabbadla/algeria-fire-map/blob/main/apps/web/components/RiskPanel.tsx): `apps/web/components/RiskPanel.tsx`
- [Restoration view](https://github.com/moussaabbadla/algeria-fire-map/blob/main/apps/web/components/RestoreDashboard.tsx): `apps/web/components/RestoreDashboard.tsx`
- [Statistics views](https://github.com/moussaabbadla/algeria-fire-map/blob/main/apps/web/components/StatsView.tsx): `apps/web/components/StatsView.tsx`
- [Stats charts](https://github.com/moussaabbadla/algeria-fire-map/blob/main/apps/web/components/statsCharts.tsx): `apps/web/components/statsCharts.tsx`
- [Wilaya choropleth](https://github.com/moussaabbadla/algeria-fire-map/blob/main/apps/web/components/NationalChoropleth.tsx): `apps/web/components/NationalChoropleth.tsx`
- [API client](https://github.com/moussaabbadla/algeria-fire-map/blob/main/apps/web/lib/api.ts): `apps/web/lib/api.ts`

### API products

- [FastAPI service](https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/main.py): `services/api/app/main.py`
- [Fire and event APIs](https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/routers/fires.py): `services/api/app/routers/fires.py`
- [At-risk API](https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/routers/at_risk.py): `services/api/app/routers/at_risk.py`
- [Weather risk API](https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/routers/risk.py): `services/api/app/routers/risk.py`
- [Restoration API](https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/routers/restoration.py): `services/api/app/routers/restoration.py`
- [Statistics API](https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/routers/stats.py): `services/api/app/routers/stats.py`
- [Forecast API](https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/routers/forecast.py): `services/api/app/routers/forecast.py`

### Data lifecycle

- [FIRMS ingestion](https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/ingest.py): `services/api/app/ingest.py`
- [FIRMS fetch](https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/firms.py): `services/api/app/firms.py`
- [Incident clustering](https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/cluster.py): `services/api/app/cluster.py`
- [Burn-scar land cover](https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/landcover.py): `services/api/app/landcover.py`
- [Burn severity](https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/severity.py): `services/api/app/severity.py`
- [Grid risk prediction](https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/predict.py): `services/api/app/predict.py`
- [Place risk analysis](https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/places.py): `services/api/app/places.py`
- [Statistics aggregation](https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/stats.py): `services/api/app/stats.py`

### State and providers

- [Weather provider](https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/weather.py): `services/api/app/weather.py`
- [FWI calculation](https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/fwi.py): `services/api/app/fwi.py`
- [Postgres / PostGIS](https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/db.py): `services/api/app/db.py`
- [Response cache](https://github.com/moussaabbadla/algeria-fire-map/blob/main/services/api/app/cache.py): `services/api/app/cache.py`

### Other components

- **Map visitor**
- **NASA FIRMS**
- **Open-Meteo**
- **Earth Engine**

## Connections

- Map visitor → Fire dashboard: explores (evidence: `README.md`)
- Fire dashboard → API client: requests data (evidence: `README.md`)
- Fire dashboard → Fire map: displays
- Fire dashboard → Timeline replay: offers replay
- Map visitor → At-risk communities: views exposure (evidence: `README.md`)
- At-risk communities → API client: requests data (evidence: `README.md`)
- Map visitor → FWI risk view: views danger (evidence: `README.md`)
- FWI risk view → API client: requests data (evidence: `README.md`)
- Map visitor → Restoration view: views recovery (evidence: `README.md`)
- Restoration view → API client: requests data (evidence: `README.md`)
- Map visitor → Statistics views: explores history (evidence: `README.md`)
- Statistics views → Stats charts: renders (evidence: `apps/web/components/StatsView.tsx`)
- Statistics views → Wilaya choropleth: renders (evidence: `apps/web/components/StatsView.tsx`)
- Statistics views → API client: requests data
- API client → FastAPI service: calls HTTPS API (evidence: `README.md`)
- FastAPI service → Fire and event APIs: registers routes (evidence: `services/api/app/main.py`)
- FastAPI service → At-risk API: registers routes (evidence: `services/api/app/main.py`)
- FastAPI service → Weather risk API: registers routes (evidence: `services/api/app/main.py`)
- FastAPI service → Restoration API: registers routes (evidence: `services/api/app/main.py`)
- FastAPI service → Statistics API: registers routes (evidence: `services/api/app/main.py`)
- FastAPI service → Forecast API: registers routes (evidence: `services/api/app/main.py`)
- FastAPI service → FIRMS ingestion: starts scheduler (evidence: `services/api/app/main.py`)
- Fire and event APIs → FIRMS fetch: fetches detections (evidence: `services/api/app/routers/fires.py`)
- Fire and event APIs → Response cache: reads cache (evidence: `services/api/app/routers/fires.py`)
- At-risk API → Place risk analysis: queries communities (evidence: `services/api/app/routers/at_risk.py`)
- At-risk API → Response cache: reads cache (evidence: `services/api/app/routers/at_risk.py`)
- Weather risk API → Weather provider: fetches weather (evidence: `services/api/app/routers/risk.py`)
- Weather risk API → FWI calculation: computes index (evidence: `services/api/app/routers/risk.py`)
- Weather risk API → Response cache: reads and writes (evidence: `services/api/app/routers/risk.py`)
- Restoration API → Response cache: reads cache (evidence: `services/api/app/routers/restoration.py`)
- Restoration API → Postgres / PostGIS: serves scar data
- Statistics API → Statistics aggregation: queries summaries (evidence: `services/api/app/routers/stats.py`)
- Forecast API → Postgres / PostGIS: reads predictions (evidence: `services/api/app/routers/forecast.py`)
- Forecast API → Response cache: reads and writes (evidence: `services/api/app/routers/forecast.py`)
- FIRMS ingestion → FIRMS fetch: fetches fires (evidence: `services/api/app/ingest.py`)
- FIRMS ingestion → Postgres / PostGIS: upserts detections (evidence: `services/api/app/ingest.py`)
- FIRMS ingestion → Incident clustering: reclusters events (evidence: `services/api/app/ingest.py`)
- FIRMS ingestion → Statistics aggregation: refreshes rollups (evidence: `services/api/app/ingest.py`)
- FIRMS ingestion → Burn-scar land cover: schedules enrichment (evidence: `services/api/app/ingest.py`)
- FIRMS ingestion → Burn severity: schedules enrichment (evidence: `services/api/app/ingest.py`)
- FIRMS ingestion → Grid risk prediction: schedules scoring (evidence: `services/api/app/ingest.py`)
- FIRMS fetch → NASA FIRMS: fetches satellite data (evidence: `services/api/app/firms.py`)
- Incident clustering → Postgres / PostGIS: updates incidents (evidence: `services/api/app/cluster.py`)
- Burn-scar land cover → Postgres / PostGIS: enriches scar records (evidence: `services/api/app/landcover.py`)
- Burn-scar land cover → Earth Engine: queries land cover (evidence: `README.md`)
- Burn severity → Postgres / PostGIS: stores severity (evidence: `services/api/app/severity.py`)
- Grid risk prediction → Postgres / PostGIS: writes cell scores (evidence: `services/api/app/main.py`)
- Place risk analysis → Postgres / PostGIS: queries places and fires (evidence: `services/api/app/places.py`)
