# syedarsalana789/aqua_twin architecture

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

- Interactive diagram: https://gitdiagram.com/syedarsalana789/aqua_twin
- Repository: https://github.com/syedarsalana789/aqua_twin

## Overview

AquaTwin is a local PHP/MySQL flood-monitoring system for public users, administrators, and assigned area operators. The public workflow combines configured gauge observations, FFD river-discharge data, GloFAS history and outlook, and flood-map overlays; staff manage stations, thresholds, notices, and imported data, while operators submit readings and incident reports. The diagram includes documented capabilities whose implementation was not sampled; those relationships rely on README evidence rather than inspection of their source.

Main entry points: [`public/index.php`](https://github.com/syedarsalana789/aqua_twin/blob/main/public/index.php) (Flood dashboard), [`database/twin_db.sql`](https://github.com/syedarsalana789/aqua_twin/blob/main/database/twin_db.sql) (AquaTwin database), [`app/ffd_sync.php`](https://github.com/syedarsalana789/aqua_twin/blob/main/app/ffd_sync.php) (FFD fetch and parser), [`app/bootstrap.php`](https://github.com/syedarsalana789/aqua_twin/blob/main/app/bootstrap.php) (Session and DB setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public monitoring"]
  node_dashboard["Flood dashboard<br/>[index.php]"]
  node_web_client["Map and dashboard client<br/>[app.js]"]
  node_ffd_view["FFD portal embed<br/>[ffd_embed.php]"]
  node_gfm_overlay["GFM map overlay"]
end

subgraph group_ingest["Flood data"]
  node_ffd_api["FFD data endpoint<br/>[ffd.php]"]
  node_ffd_sync["FFD fetch and parser<br/>[ffd_sync.php]"]
  node_ffd_service{{"Official FFD portal"}}
  node_forecast_api["Forecast and risk API<br/>[prediction.php]"]
  node_flood_api["Discharge history API<br/>[flood.php]"]
  node_glofas{{"Open-Meteo GloFAS"}}
  node_scheduler["Scheduled sync<br/>[sync_ffd.php]"]
end

subgraph group_staff["Staff operations"]
  node_admin_page["Admin dashboard<br/>[admin.php]"]
  node_admin_data["Admin data actions<br/>[admin_data.php]"]
  node_operator_page["Operator dashboard<br/>[operator.php]"]
  node_login["Staff sign-in<br/>[login.php]"]
end

subgraph group_core["Application core"]
  node_database[("AquaTwin database<br/>[twin_db.sql]")]
  node_bootstrap["Session and DB setup<br/>[bootstrap.php]"]
  node_helpers["Auth and audit helpers<br/>[helpers.php]"]
  node_db_config["Database settings<br/>[database.php]"]
end

node_visitor(("Public visitor"))
node_admin_actor(("Administrator"))
node_operator_actor(("Area operator"))

node_visitor -->|"opens"| node_dashboard
node_dashboard -.->|"renders"| node_web_client
node_web_client -.->|"requests data"| node_ffd_api
node_dashboard -.->|"requests outlook"| node_forecast_api
node_dashboard -.->|"requests history"| node_flood_api
node_dashboard -.->|"offers overlay"| node_gfm_overlay
node_dashboard -.->|"embeds portal"| node_ffd_view
node_ffd_api -->|"calls when stale"| node_ffd_sync
node_ffd_sync -->|"fetches and parses"| node_ffd_service
node_ffd_sync -->|"stores readings"| node_database
node_forecast_api -->|"fetches forecast"| node_glofas
node_forecast_api -->|"stores outlook"| node_database
node_flood_api -.->|"fetches discharge"| node_glofas
node_admin_actor -->|"manages"| node_admin_page
node_admin_actor -->|"imports and configures"| node_admin_data
node_admin_data -->|"starts manual sync"| node_ffd_sync
node_admin_data -.->|"updates monitoring data"| node_database
node_operator_actor -->|"submits readings"| node_operator_page
node_operator_page -.->|"records readings and incidents"| node_database
node_login -->|"checks account"| node_database
node_login -->|"audits sign-in"| node_helpers
node_scheduler -->|"runs sync"| node_ffd_sync
node_bootstrap -->|"loads settings"| node_db_config
node_bootstrap -->|"loads helpers"| node_helpers
node_bootstrap -->|"opens connection"| node_database

click node_dashboard "https://github.com/syedarsalana789/aqua_twin/blob/main/public/index.php"
click node_web_client "https://github.com/syedarsalana789/aqua_twin/blob/main/public/assets/app.js"
click node_ffd_view "https://github.com/syedarsalana789/aqua_twin/blob/main/public/api/ffd_embed.php"
click node_gfm_overlay "https://github.com/syedarsalana789/aqua_twin/blob/main/public/api/gfm_capabilities.php"
click node_ffd_api "https://github.com/syedarsalana789/aqua_twin/blob/main/public/api/ffd.php"
click node_ffd_sync "https://github.com/syedarsalana789/aqua_twin/blob/main/app/ffd_sync.php"
click node_forecast_api "https://github.com/syedarsalana789/aqua_twin/blob/main/public/api/prediction.php"
click node_flood_api "https://github.com/syedarsalana789/aqua_twin/blob/main/public/api/flood.php"
click node_admin_page "https://github.com/syedarsalana789/aqua_twin/blob/main/public/admin.php"
click node_admin_data "https://github.com/syedarsalana789/aqua_twin/blob/main/public/admin_data.php"
click node_operator_page "https://github.com/syedarsalana789/aqua_twin/blob/main/public/operator.php"
click node_login "https://github.com/syedarsalana789/aqua_twin/blob/main/public/login.php"
click node_scheduler "https://github.com/syedarsalana789/aqua_twin/blob/main/cron/sync_ffd.php"
click node_database "https://github.com/syedarsalana789/aqua_twin/blob/main/database/twin_db.sql"
click node_bootstrap "https://github.com/syedarsalana789/aqua_twin/blob/main/app/bootstrap.php"
click node_helpers "https://github.com/syedarsalana789/aqua_twin/blob/main/app/helpers.php"
click node_db_config "https://github.com/syedarsalana789/aqua_twin/blob/main/config/database.php"

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_dashboard,node_web_client,node_ffd_view,node_gfm_overlay toneBlue
class node_ffd_api,node_ffd_sync,node_ffd_service,node_forecast_api,node_flood_api,node_glofas,node_scheduler toneAmber
class node_admin_page,node_admin_data,node_operator_page,node_login toneMint
class node_database,node_bootstrap,node_helpers,node_db_config toneRose
class node_visitor,node_admin_actor,node_operator_actor toneIndigo
```

## Components

### Public monitoring

- [Flood dashboard](https://github.com/syedarsalana789/aqua_twin/blob/main/public/index.php): `public/index.php`
- [Map and dashboard client](https://github.com/syedarsalana789/aqua_twin/blob/main/public/assets/app.js): `public/assets/app.js`
- [FFD portal embed](https://github.com/syedarsalana789/aqua_twin/blob/main/public/api/ffd_embed.php): `public/api/ffd_embed.php`
- [GFM map overlay](https://github.com/syedarsalana789/aqua_twin/blob/main/public/api/gfm_capabilities.php): `public/api/gfm_capabilities.php`

### Flood data

- [FFD data endpoint](https://github.com/syedarsalana789/aqua_twin/blob/main/public/api/ffd.php): `public/api/ffd.php`
- [FFD fetch and parser](https://github.com/syedarsalana789/aqua_twin/blob/main/app/ffd_sync.php): `app/ffd_sync.php`
- **Official FFD portal**
- [Forecast and risk API](https://github.com/syedarsalana789/aqua_twin/blob/main/public/api/prediction.php): `public/api/prediction.php`
- [Discharge history API](https://github.com/syedarsalana789/aqua_twin/blob/main/public/api/flood.php): `public/api/flood.php`
- **Open-Meteo GloFAS**
- [Scheduled sync](https://github.com/syedarsalana789/aqua_twin/blob/main/cron/sync_ffd.php): `cron/sync_ffd.php`

### Staff operations

- [Admin dashboard](https://github.com/syedarsalana789/aqua_twin/blob/main/public/admin.php): `public/admin.php`
- [Admin data actions](https://github.com/syedarsalana789/aqua_twin/blob/main/public/admin_data.php): `public/admin_data.php`
- [Operator dashboard](https://github.com/syedarsalana789/aqua_twin/blob/main/public/operator.php): `public/operator.php`
- [Staff sign-in](https://github.com/syedarsalana789/aqua_twin/blob/main/public/login.php): `public/login.php`

### Application core

- [AquaTwin database](https://github.com/syedarsalana789/aqua_twin/blob/main/database/twin_db.sql): `database/twin_db.sql`
- [Session and DB setup](https://github.com/syedarsalana789/aqua_twin/blob/main/app/bootstrap.php): `app/bootstrap.php`
- [Auth and audit helpers](https://github.com/syedarsalana789/aqua_twin/blob/main/app/helpers.php): `app/helpers.php`
- [Database settings](https://github.com/syedarsalana789/aqua_twin/blob/main/config/database.php): `config/database.php`

### Other components

- **Public visitor**
- **Administrator**
- **Area operator**

## Connections

- Public visitor → Flood dashboard: opens (evidence: `README.md`)
- Flood dashboard → Map and dashboard client: renders
- Map and dashboard client → FFD data endpoint: requests data
- Flood dashboard → Forecast and risk API: requests outlook
- Flood dashboard → Discharge history API: requests history
- Flood dashboard → GFM map overlay: offers overlay
- Flood dashboard → FFD portal embed: embeds portal
- FFD data endpoint → FFD fetch and parser: calls when stale (evidence: `public/api/ffd.php`)
- FFD fetch and parser → Official FFD portal: fetches and parses (evidence: `app/ffd_sync.php`)
- FFD fetch and parser → AquaTwin database: stores readings (evidence: `app/ffd_sync.php`)
- Forecast and risk API → Open-Meteo GloFAS: fetches forecast (evidence: `public/api/prediction.php`)
- Forecast and risk API → AquaTwin database: stores outlook (evidence: `public/api/prediction.php`)
- Discharge history API → Open-Meteo GloFAS: fetches discharge
- Administrator → Admin dashboard: manages (evidence: `README.md`)
- Administrator → Admin data actions: imports and configures (evidence: `README.md`)
- Admin data actions → FFD fetch and parser: starts manual sync (evidence: `public/admin_data.php`)
- Admin data actions → AquaTwin database: updates monitoring data
- Area operator → Operator dashboard: submits readings (evidence: `README.md`)
- Operator dashboard → AquaTwin database: records readings and incidents
- Staff sign-in → AquaTwin database: checks account (evidence: `public/login.php`)
- Staff sign-in → Auth and audit helpers: audits sign-in (evidence: `public/login.php`)
- Scheduled sync → FFD fetch and parser: runs sync (evidence: `cron/sync_ffd.php`)
- Session and DB setup → Database settings: loads settings (evidence: `app/bootstrap.php`)
- Session and DB setup → Auth and audit helpers: loads helpers (evidence: `app/bootstrap.php`)
- Session and DB setup → AquaTwin database: opens connection (evidence: `app/bootstrap.php`)
