# maki-sig/flood-prediction-test architecture

> Architecture diagram of the GitHub repository maki-sig/flood-prediction-test, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maki-sig/flood-prediction-test
- Repository: https://github.com/maki-sig/flood-prediction-test

## Overview

FLOWS is a flood-risk forecasting and evacuation-support application for Naga City. Its primary workflow presents a three-day hourly forecast and risk map in the dashboard; shelter data can also be managed and used to plan evacuation routes. The README documents a Next.js frontend, FastAPI inference service, XGBoost model, Supabase, and Open-Meteo, but sampled source does not expose the forecast request chain or backend internals. Those connections are marked unverified; shelter CRUD and map-planning calls are visible in the excerpts.

Main entry points: [`frontend/app/dashboard/page.tsx`](https://github.com/maki-sig/flood-prediction-test/blob/main/frontend/app/dashboard/page.tsx) (Forecast Dashboard), [`frontend/app/components/FloodMap.tsx`](https://github.com/maki-sig/flood-prediction-test/blob/main/frontend/app/components/FloodMap.tsx) (Interactive Flood Map), [`backend/app.py`](https://github.com/maki-sig/flood-prediction-test/blob/main/backend/app.py) (Inference Service), [`backend/train.py`](https://github.com/maki-sig/flood-prediction-test/blob/main/backend/train.py) (Model Training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_forecast["Forecasting"]
  node_predict_route["Prediction API<br/>[route.ts]"]
  node_fastapi["Inference Service<br/>[app.py]"]
  node_model["XGBoost Model<br/>[flood_model.pkl]"]
  node_training["Model Training<br/>[train.py]"]
  node_feature_prep["Feature Preparation<br/>[features-prep.py]"]
  node_historical_data["Historical Data"]
  node_flood_features["Flood Features<br/>[flood_features.csv]"]
end

subgraph group_dashboard["Dashboard"]
  node_dashboard_page["Forecast Dashboard<br/>[page.tsx]"]
  node_map["Interactive Flood Map<br/>[FloodMap.tsx]"]
end

subgraph group_shelters["Shelter Operations"]
  node_shelter_actions["Shelter API Client<br/>[evac-actions.ts]"]
  node_shelter_api["Shelter API Route<br/>[route.ts]"]
  node_supabase_client["Supabase Client<br/>[supabase.ts]"]
  node_manage_evac["Shelter Management<br/>[page.tsx]"]
  node_login["Login<br/>[page.tsx]"]
end

subgraph group_routing["Evacuation Routing"]
  node_route_planner["Shelter Route Planner<br/>[route-planner.ts]"]
  node_recommendation["Shelter Recommendation"]
  node_route_service["Road Route Service<br/>[route-service.ts]"]
end

node_user(("Dashboard User"))
node_open_meteo["Open-Meteo"]
node_supabase[("Supabase Database")]
node_osrm["OSRM Routing"]

node_user -->|"views forecast"| node_dashboard_page
node_dashboard_page -.->|"requests forecast"| node_predict_route
node_predict_route -.->|"forwards inference"| node_fastapi
node_fastapi -.->|"uses classifier"| node_model
node_open_meteo -.->|"provides weather"| node_fastapi
node_historical_data -.->|"trains from"| node_training
node_feature_prep -.->|"prepares features"| node_training
node_training -.->|"produces model"| node_model
node_dashboard_page -->|"renders"| node_map
node_dashboard_page -->|"fetches pins"| node_shelter_actions
node_manage_evac -->|"manages shelters"| node_shelter_actions
node_shelter_actions -->|"calls endpoint"| node_shelter_api
node_shelter_api -->|"uses client"| node_supabase_client
node_supabase_client -.->|"accesses database"| node_supabase
node_login -->|"authenticates"| node_supabase_client
node_map -->|"plans shelter route"| node_route_planner
node_route_planner -->|"selects shelter"| node_recommendation
node_map -->|"requests road route"| node_route_service
node_route_service -->|"fetches route"| node_osrm

click node_dashboard_page "https://github.com/maki-sig/flood-prediction-test/blob/main/frontend/app/dashboard/page.tsx"
click node_predict_route "https://github.com/maki-sig/flood-prediction-test/blob/main/frontend/app/api/predict/route.ts"
click node_fastapi "https://github.com/maki-sig/flood-prediction-test/blob/main/backend/app.py"
click node_model "https://github.com/maki-sig/flood-prediction-test/blob/main/model/flood_model.pkl"
click node_training "https://github.com/maki-sig/flood-prediction-test/blob/main/backend/train.py"
click node_feature_prep "https://github.com/maki-sig/flood-prediction-test/blob/main/backend/features-prep.py"
click node_historical_data "https://github.com/maki-sig/flood-prediction-test/blob/main/data/vks-one-yr-rain-history.csv"
click node_flood_features "https://github.com/maki-sig/flood-prediction-test/blob/main/data/flood_features.csv"
click node_map "https://github.com/maki-sig/flood-prediction-test/blob/main/frontend/app/components/FloodMap.tsx"
click node_shelter_actions "https://github.com/maki-sig/flood-prediction-test/blob/main/frontend/lib/evac-actions.ts"
click node_shelter_api "https://github.com/maki-sig/flood-prediction-test/blob/main/frontend/app/api/shelters/route.ts"
click node_supabase_client "https://github.com/maki-sig/flood-prediction-test/blob/main/frontend/lib/supabase.ts"
click node_manage_evac "https://github.com/maki-sig/flood-prediction-test/blob/main/frontend/app/manage-evac/page.tsx"
click node_login "https://github.com/maki-sig/flood-prediction-test/blob/main/frontend/app/login/page.tsx"
click node_route_planner "https://github.com/maki-sig/flood-prediction-test/blob/main/frontend/lib/route-planner.ts"
click node_recommendation "https://github.com/maki-sig/flood-prediction-test/blob/main/frontend/lib/shelter-recommendation.ts"
click node_route_service "https://github.com/maki-sig/flood-prediction-test/blob/main/frontend/lib/route-service.ts"

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_predict_route,node_fastapi,node_model,node_training,node_feature_prep,node_historical_data,node_flood_features,node_user toneBlue
class node_dashboard_page,node_map,node_supabase toneAmber
class node_shelter_actions,node_shelter_api,node_supabase_client,node_manage_evac,node_login toneMint
class node_route_planner,node_recommendation,node_route_service toneRose
class node_open_meteo,node_osrm toneIndigo
```

## Components

### Forecasting

- [Prediction API](https://github.com/maki-sig/flood-prediction-test/blob/main/frontend/app/api/predict/route.ts): `frontend/app/api/predict/route.ts`
- [Inference Service](https://github.com/maki-sig/flood-prediction-test/blob/main/backend/app.py): `backend/app.py`
- [XGBoost Model](https://github.com/maki-sig/flood-prediction-test/blob/main/model/flood_model.pkl): `model/flood_model.pkl`
- [Model Training](https://github.com/maki-sig/flood-prediction-test/blob/main/backend/train.py): `backend/train.py`
- [Feature Preparation](https://github.com/maki-sig/flood-prediction-test/blob/main/backend/features-prep.py): `backend/features-prep.py`
- [Historical Data](https://github.com/maki-sig/flood-prediction-test/blob/main/data/vks-one-yr-rain-history.csv): `data/vks-one-yr-rain-history.csv`
- [Flood Features](https://github.com/maki-sig/flood-prediction-test/blob/main/data/flood_features.csv): `data/flood_features.csv`

### Dashboard

- [Forecast Dashboard](https://github.com/maki-sig/flood-prediction-test/blob/main/frontend/app/dashboard/page.tsx): `frontend/app/dashboard/page.tsx`
- [Interactive Flood Map](https://github.com/maki-sig/flood-prediction-test/blob/main/frontend/app/components/FloodMap.tsx): `frontend/app/components/FloodMap.tsx`

### Shelter Operations

- [Shelter API Client](https://github.com/maki-sig/flood-prediction-test/blob/main/frontend/lib/evac-actions.ts): `frontend/lib/evac-actions.ts`
- [Shelter API Route](https://github.com/maki-sig/flood-prediction-test/blob/main/frontend/app/api/shelters/route.ts): `frontend/app/api/shelters/route.ts`
- [Supabase Client](https://github.com/maki-sig/flood-prediction-test/blob/main/frontend/lib/supabase.ts): `frontend/lib/supabase.ts`
- [Shelter Management](https://github.com/maki-sig/flood-prediction-test/blob/main/frontend/app/manage-evac/page.tsx): `frontend/app/manage-evac/page.tsx`
- [Login](https://github.com/maki-sig/flood-prediction-test/blob/main/frontend/app/login/page.tsx): `frontend/app/login/page.tsx`

### Evacuation Routing

- [Shelter Route Planner](https://github.com/maki-sig/flood-prediction-test/blob/main/frontend/lib/route-planner.ts): `frontend/lib/route-planner.ts`
- [Shelter Recommendation](https://github.com/maki-sig/flood-prediction-test/blob/main/frontend/lib/shelter-recommendation.ts): `frontend/lib/shelter-recommendation.ts`
- [Road Route Service](https://github.com/maki-sig/flood-prediction-test/blob/main/frontend/lib/route-service.ts): `frontend/lib/route-service.ts`

### Other components

- **Dashboard User**
- **Open-Meteo**
- **Supabase Database**
- **OSRM Routing**

## Connections

- Dashboard User → Forecast Dashboard: views forecast (evidence: `README.md`)
- Forecast Dashboard → Prediction API: requests forecast
- Prediction API → Inference Service: forwards inference
- Inference Service → XGBoost Model: uses classifier
- Open-Meteo → Inference Service: provides weather
- Historical Data → Model Training: trains from
- Feature Preparation → Model Training: prepares features
- Model Training → XGBoost Model: produces model (evidence: `README.md`)
- Forecast Dashboard → Interactive Flood Map: renders (evidence: `frontend/app/dashboard/page.tsx`)
- Forecast Dashboard → Shelter API Client: fetches pins (evidence: `frontend/app/dashboard/page.tsx`)
- Shelter Management → Shelter API Client: manages shelters (evidence: `frontend/app/manage-evac/page.tsx`)
- Shelter API Client → Shelter API Route: calls endpoint (evidence: `frontend/lib/evac-actions.ts`)
- Shelter API Route → Supabase Client: uses client (evidence: `frontend/app/api/shelters/route.ts`)
- Supabase Client → Supabase Database: accesses database
- Login → Supabase Client: authenticates (evidence: `frontend/app/login/page.tsx`)
- Interactive Flood Map → Shelter Route Planner: plans shelter route (evidence: `frontend/app/components/FloodMap.tsx`)
- Shelter Route Planner → Shelter Recommendation: selects shelter (evidence: `frontend/lib/route-planner.ts`)
- Interactive Flood Map → Road Route Service: requests road route (evidence: `frontend/app/components/FloodMap.tsx`)
- Road Route Service → OSRM Routing: fetches route (evidence: `frontend/lib/route-service.ts`)