# rscence-2026-uptac/project-pia-waterback architecture

> Architecture diagram of the GitHub repository rscence-2026-uptac/project-pia-waterback, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rscence-2026-uptac/project-pia-waterback
- Repository: https://github.com/rscence-2026-uptac/project-pia-waterback

## Overview

PIA Waterback supports residents and local water-response teams during water disruptions. Its workflow moves from rainfall and utility signals through disruption prediction, affected-area assessment, and backup-source ranking to LGU allocation, resident notification, and restoration confirmation. The web app presents resident, captain, operator, and LGU views, with sample-data and offline modes alongside live Supabase access. The graph preserves documented product branches, including planning and the predictor’s synthetic-training pipeline. Some Edge Function internals and unsampled screens are represented only at their documented boundaries.

Main entry points: [`apps/web/src/api/endpoints.ts`](https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/apps/web/src/api/endpoints.ts) (Function API), [`apps/web/src/screens/lgu`](https://github.com/rscence-2026-uptac/project-pia-waterback/tree/main/apps/web/src/screens/lgu) (LGU response views), [`apps/web/src/main.tsx`](https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/apps/web/src/main.tsx) (App routing), [`apps/web/src/screens/resident`](https://github.com/rscence-2026-uptac/project-pia-waterback/tree/main/apps/web/src/screens/resident) (Resident views)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web app"]
  node_web_entry["App routing<br/>[main.tsx]"]
  node_resident_views["Resident views"]
  node_captain_view["Captain view<br/>[CaptainScreen.tsx]"]
  node_operator_view["Operator view<br/>[OperatorScreen.tsx]"]
  node_lgu_views["LGU response views"]
  node_status_data["Status retrieval<br/>[status.ts]"]
  node_offline_status["Cached status"]
  node_realtime["Realtime dashboard<br/>[useDashboard.ts]"]
  node_api_endpoints["Function API<br/>[endpoints.ts]"]
  node_mock_data["Sample data<br/>[mock.ts]"]
  node_copy["Language and copy<br/>[i18n.ts]"]
end

subgraph group_response["Disruption response"]
  node_monitor["Disruption monitor<br/>[index.ts]"]
  node_predictor["Disruption prediction<br/>[index.ts]"]
  node_predictor_handler["Prediction handler<br/>[handler.ts]"]
  node_predict_logic["Forecast and prediction<br/>[predict.ts]"]
  node_affected["Affected areas<br/>[index.ts]"]
  node_ranking["Backup-source ranking<br/>[index.ts]"]
  node_allocation["Allocation decisions<br/>[index.ts]"]
  node_deployment["Response deployment<br/>[index.ts]"]
  node_notification["Resident notification<br/>[index.ts]"]
  node_sms["SMS replies<br/>[index.ts]"]
  node_confirmation["Restoration confirmation<br/>[index.ts]"]
  node_dashboard_snapshot["Dashboard snapshot<br/>[index.ts]"]
end

subgraph group_shared["Contracts and data"]
  node_shared_types["Shared schemas"]
  node_source_data["Seeded sources<br/>[seedSources.ts]"]
  node_planning["Water-access planning<br/>[PlanScreen.tsx]"]
end

subgraph group_ml["Predictor development"]
  node_synthetic["Synthetic trajectories<br/>[synthetic.py]"]
  node_simulation["July simulation<br/>[simulate_july.py]"]
  node_training["Model training<br/>[train_predictor.py]"]
  node_model_lib["Model utilities<br/>[v3_lib.py]"]
end

node_residents(("Residents"))
node_response_staff(("Response staff"))
node_supabase[("Supabase")]

node_web_entry -->|"routes to"| node_resident_views
node_web_entry -->|"routes to"| node_captain_view
node_web_entry -->|"routes to"| node_operator_view
node_web_entry -->|"routes to"| node_lgu_views
node_residents -.->|"views status"| node_resident_views
node_response_staff -.->|"reviews readings"| node_operator_view
node_response_staff -.->|"plans response"| node_lgu_views
node_resident_views -->|"loads status"| node_offline_status
node_captain_view -->|"loads status"| node_offline_status
node_offline_status -->|"fetches live"| node_status_data
node_offline_status -->|"uses fallback"| node_mock_data
node_status_data -.->|"reads live data"| node_supabase
node_operator_view -->|"calls API"| node_api_endpoints
node_lgu_views -->|"calls API"| node_api_endpoints
node_api_endpoints -->|"calls function"| node_predictor
node_api_endpoints -->|"calls function"| node_affected
node_api_endpoints -->|"calls function"| node_ranking
node_api_endpoints -->|"calls function"| node_monitor
node_api_endpoints -->|"calls function"| node_dashboard_snapshot
node_predictor -->|"delegates to"| node_predictor_handler
node_predictor_handler -->|"calls prediction"| node_predict_logic
node_lgu_views -.->|"presents plan"| node_planning
node_lgu_views -->|"uses source data"| node_source_data
node_resident_views -->|"uses translations"| node_copy
node_operator_view -.->|"shows live updates"| node_realtime
node_sms -.->|"confirms restoration"| node_confirmation
node_sms -.->|"records messages"| node_supabase
node_notification -.->|"writes notifications"| node_supabase
node_dashboard_snapshot -.->|"reads snapshot data"| node_supabase
node_shared_types -.->|"defines contracts"| node_api_endpoints
node_synthetic -->|"reuses simulation"| node_simulation
node_training -->|"builds training data"| node_synthetic
node_training -->|"uses simulated data"| node_simulation
node_training -->|"uses utilities"| node_model_lib

click node_web_entry "https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/apps/web/src/main.tsx"
click node_resident_views "https://github.com/rscence-2026-uptac/project-pia-waterback/tree/main/apps/web/src/screens/resident"
click node_captain_view "https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/apps/web/src/screens/captain/CaptainScreen.tsx"
click node_operator_view "https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/apps/web/src/screens/operator/OperatorScreen.tsx"
click node_lgu_views "https://github.com/rscence-2026-uptac/project-pia-waterback/tree/main/apps/web/src/screens/lgu"
click node_status_data "https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/apps/web/src/api/status.ts"
click node_offline_status "https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/apps/web/src/offline/useBarangayStatus.ts"
click node_realtime "https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/apps/web/src/realtime/useDashboard.ts"
click node_api_endpoints "https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/apps/web/src/api/endpoints.ts"
click node_mock_data "https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/apps/web/src/data/mock.ts"
click node_copy "https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/apps/web/src/copy/i18n.ts"
click node_monitor "https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/supabase/functions/disruption-monitor/index.ts"
click node_predictor "https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/supabase/functions/disruption-predictor/index.ts"
click node_predictor_handler "https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/supabase/functions/_shared/handler.ts"
click node_predict_logic "https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/supabase/functions/_shared/predict.ts"
click node_affected "https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/supabase/functions/affected-areas/index.ts"
click node_ranking "https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/supabase/functions/rank-chain/index.ts"
click node_allocation "https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/supabase/functions/confirm-allocation/index.ts"
click node_deployment "https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/supabase/functions/deploy-response/index.ts"
click node_notification "https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/supabase/functions/notify-residents/index.ts"
click node_sms "https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/supabase/functions/sms-webhook/index.ts"
click node_confirmation "https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/supabase/functions/resident-confirmation/index.ts"
click node_dashboard_snapshot "https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/supabase/functions/dashboard-snapshot/index.ts"
click node_shared_types "https://github.com/rscence-2026-uptac/project-pia-waterback/tree/main/packages/shared-types/src/schemas"
click node_source_data "https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/apps/web/src/data/seedSources.ts"
click node_planning "https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/apps/web/src/screens/lgu/PlanScreen.tsx"
click node_synthetic "https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/ml/synthetic.py"
click node_simulation "https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/ml/simulate_july.py"
click node_training "https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/ml/train_predictor.py"
click node_model_lib "https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/ml/v3_lib.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_web_entry,node_resident_views,node_captain_view,node_operator_view,node_lgu_views,node_status_data,node_offline_status,node_realtime,node_api_endpoints,node_mock_data,node_copy toneBlue
class node_monitor,node_predictor,node_predictor_handler,node_predict_logic,node_affected,node_ranking,node_allocation,node_deployment,node_notification,node_sms,node_confirmation,node_dashboard_snapshot,node_supabase toneAmber
class node_shared_types,node_source_data,node_planning toneMint
class node_synthetic,node_simulation,node_training,node_model_lib toneRose
class node_residents,node_response_staff toneIndigo
```

## Components

### Web app

- [App routing](https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/apps/web/src/main.tsx): `apps/web/src/main.tsx`
- [Resident views](https://github.com/rscence-2026-uptac/project-pia-waterback/tree/main/apps/web/src/screens/resident): `apps/web/src/screens/resident`
- [Captain view](https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/apps/web/src/screens/captain/CaptainScreen.tsx): `apps/web/src/screens/captain/CaptainScreen.tsx`
- [Operator view](https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/apps/web/src/screens/operator/OperatorScreen.tsx): `apps/web/src/screens/operator/OperatorScreen.tsx`
- [LGU response views](https://github.com/rscence-2026-uptac/project-pia-waterback/tree/main/apps/web/src/screens/lgu): `apps/web/src/screens/lgu`
- [Status retrieval](https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/apps/web/src/api/status.ts): `apps/web/src/api/status.ts`
- [Cached status](https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/apps/web/src/offline/useBarangayStatus.ts): `apps/web/src/offline/useBarangayStatus.ts`
- [Realtime dashboard](https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/apps/web/src/realtime/useDashboard.ts): `apps/web/src/realtime/useDashboard.ts`
- [Function API](https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/apps/web/src/api/endpoints.ts): `apps/web/src/api/endpoints.ts`
- [Sample data](https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/apps/web/src/data/mock.ts): `apps/web/src/data/mock.ts`
- [Language and copy](https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/apps/web/src/copy/i18n.ts): `apps/web/src/copy/i18n.ts`

### Disruption response

- [Disruption monitor](https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/supabase/functions/disruption-monitor/index.ts): `supabase/functions/disruption-monitor/index.ts`
- [Disruption prediction](https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/supabase/functions/disruption-predictor/index.ts): `supabase/functions/disruption-predictor/index.ts`
- [Prediction handler](https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/supabase/functions/_shared/handler.ts): `supabase/functions/_shared/handler.ts`
- [Forecast and prediction](https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/supabase/functions/_shared/predict.ts): `supabase/functions/_shared/predict.ts`
- [Affected areas](https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/supabase/functions/affected-areas/index.ts): `supabase/functions/affected-areas/index.ts`
- [Backup-source ranking](https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/supabase/functions/rank-chain/index.ts): `supabase/functions/rank-chain/index.ts`
- [Allocation decisions](https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/supabase/functions/confirm-allocation/index.ts): `supabase/functions/confirm-allocation/index.ts`
- [Response deployment](https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/supabase/functions/deploy-response/index.ts): `supabase/functions/deploy-response/index.ts`
- [Resident notification](https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/supabase/functions/notify-residents/index.ts): `supabase/functions/notify-residents/index.ts`
- [SMS replies](https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/supabase/functions/sms-webhook/index.ts): `supabase/functions/sms-webhook/index.ts`
- [Restoration confirmation](https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/supabase/functions/resident-confirmation/index.ts): `supabase/functions/resident-confirmation/index.ts`
- [Dashboard snapshot](https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/supabase/functions/dashboard-snapshot/index.ts): `supabase/functions/dashboard-snapshot/index.ts`

### Contracts and data

- [Shared schemas](https://github.com/rscence-2026-uptac/project-pia-waterback/tree/main/packages/shared-types/src/schemas): `packages/shared-types/src/schemas`
- [Seeded sources](https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/apps/web/src/data/seedSources.ts): `apps/web/src/data/seedSources.ts`
- [Water-access planning](https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/apps/web/src/screens/lgu/PlanScreen.tsx): `apps/web/src/screens/lgu/PlanScreen.tsx`

### Predictor development

- [Synthetic trajectories](https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/ml/synthetic.py): `ml/synthetic.py`
- [July simulation](https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/ml/simulate_july.py): `ml/simulate_july.py`
- [Model training](https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/ml/train_predictor.py): `ml/train_predictor.py`
- [Model utilities](https://github.com/rscence-2026-uptac/project-pia-waterback/blob/main/ml/v3_lib.py): `ml/v3_lib.py`

### Other components

- **Residents**
- **Response staff**
- **Supabase**

## Connections

- App routing → Resident views: routes to (evidence: `apps/web/src/main.tsx`)
- App routing → Captain view: routes to (evidence: `apps/web/src/main.tsx`)
- App routing → Operator view: routes to (evidence: `apps/web/src/main.tsx`)
- App routing → LGU response views: routes to (evidence: `apps/web/src/main.tsx`)
- Residents → Resident views: views status
- Response staff → Operator view: reviews readings
- Response staff → LGU response views: plans response
- Resident views → Cached status: loads status (evidence: `apps/web/src/screens/resident/StatusScreen.tsx`)
- Captain view → Cached status: loads status (evidence: `apps/web/src/screens/captain/CaptainScreen.tsx`)
- Cached status → Status retrieval: fetches live (evidence: `apps/web/src/offline/useBarangayStatus.ts`)
- Cached status → Sample data: uses fallback (evidence: `apps/web/src/offline/useBarangayStatus.ts`)
- Status retrieval → Supabase: reads live data
- Operator view → Function API: calls API (evidence: `apps/web/src/screens/operator/OperatorScreen.tsx`)
- LGU response views → Function API: calls API (evidence: `apps/web/src/screens/lgu/AllocationScreen.tsx`)
- Function API → Disruption prediction: calls function (evidence: `apps/web/src/api/endpoints.ts`)
- Function API → Affected areas: calls function (evidence: `apps/web/src/api/endpoints.ts`)
- Function API → Backup-source ranking: calls function (evidence: `apps/web/src/api/endpoints.ts`)
- Function API → Disruption monitor: calls function (evidence: `apps/web/src/api/endpoints.ts`)
- Function API → Dashboard snapshot: calls function (evidence: `apps/web/src/api/endpoints.ts`)
- Disruption prediction → Prediction handler: delegates to (evidence: `supabase/functions/disruption-predictor/index.ts`)
- Prediction handler → Forecast and prediction: calls prediction (evidence: `supabase/functions/_shared/handler.ts`)
- LGU response views → Water-access planning: presents plan
- LGU response views → Seeded sources: uses source data (evidence: `apps/web/src/screens/lgu/AllocationScreen.tsx`)
- Resident views → Language and copy: uses translations (evidence: `apps/web/src/screens/resident/StatusScreen.tsx`)
- Operator view → Realtime dashboard: shows live updates
- SMS replies → Restoration confirmation: confirms restoration
- SMS replies → Supabase: records messages
- Resident notification → Supabase: writes notifications
- Dashboard snapshot → Supabase: reads snapshot data
- Shared schemas → Function API: defines contracts
- Synthetic trajectories → July simulation: reuses simulation (evidence: `ml/synthetic.py`)
- Model training → Synthetic trajectories: builds training data (evidence: `ml/train_predictor.py`)
- Model training → July simulation: uses simulated data (evidence: `ml/train_predictor.py`)
- Model training → Model utilities: uses utilities (evidence: `ml/train_predictor.py`)
