docs: rewrite all documentation to reflect current state
- Remove adminer references (service was removed) - Remove mermaid diagrams (ASCII only) - Remove hardcoded credentials (use env var references) - Update all Docker references to 4-container setup (app, postgres, web, pgadmin) - Document env-based admin credentials (ADMIN_EMAIL/ADMIN_PASSWORD) - Document parameterized queries (SQL injection fixed) - Document FCM topic routing by stationtype+level - Document siren stationtype=3 fix in sidesdecode.py - Document idempotent seeder (firstOrCreate) - Document reverse proxy setup in deployment guide - Remove Makefile references (Docker Compose only)
This commit is contained in:
root
@@ -1,71 +1,123 @@
|
||||
<!-- generated-by: gsd-doc-writer -->
|
||||
|
||||
# SIDES - Project Overview
|
||||
|
||||
## What Is SIDES?
|
||||
## What Is SIDES
|
||||
|
||||
**Sabo Integrated Debris Flow Monitoring and Early Warning System (SIDES)** is a flood and debris flow early warning system for **Sungai Kupang**, Malaysia. It is operated under **Jabatan Pengairan dan Saliran (JPS)** — the Malaysian Department of Irrigation and Drainage.
|
||||
SIDES (Sabo Integrated Debris Flow Monitoring and Early Warning System) is a web application that monitors rainfall and water level data from sensor stations in the Sungai Kupang area, Kedah, Malaysia. It is operated by JPS (Jabatan Pengairan dan Saliran / Department of Irrigation and Drainage). The system ingests real-time telemetry data, displays it on a map dashboard, and pushes Firebase Cloud Messaging (FCM) alerts when readings cross warning or danger thresholds.
|
||||
|
||||
The system monitors rainfall, water levels, and siren activations at remote telemetry stations and presents real-time data on a web dashboard with an interactive map.
|
||||
## Technology Stack
|
||||
|
||||
## Purpose
|
||||
| Layer | Technology |
|
||||
|--------------|--------------------------------|
|
||||
| Backend | Laravel 12 on PHP 8.2 |
|
||||
| Database | PostgreSQL 16 |
|
||||
| Frontend | Blade templates + Vite build |
|
||||
| Auth | Laravel Breeze (session-based) |
|
||||
| Notifications| Firebase Cloud Messaging (FCM) |
|
||||
| Deployment | Docker Compose |
|
||||
| PDF Export | barryvdh/laravel-dompdf |
|
||||
| Excel Export | maatwebsite/excel |
|
||||
|
||||
SIDES provides:
|
||||
## Architecture
|
||||
|
||||
- **Real-time monitoring** of hydrological and meteorological data from field stations
|
||||
- **Early warning alerts** when rainfall or water levels exceed danger thresholds
|
||||
- **Siren status tracking** for stations equipped with warning sirens
|
||||
- **Historical data analysis** with exportable reports (Excel, PDF)
|
||||
- **Push notifications** to mobile devices via Firebase Cloud Messaging (FCM)
|
||||
- **Admin management** of stations, users, and access control
|
||||
```
|
||||
Internet
|
||||
|
|
||||
Reverse Proxy
|
||||
(TLS termination)
|
||||
|
|
||||
+--------------+--------------+
|
||||
| Docker Network |
|
||||
| |
|
||||
+----+----+ +---------+ +-------+-----+ +---------+
|
||||
| nginx | | php-fpm | | PostgreSQL | | pgAdmin |
|
||||
| :80 +--->| :9000 +--->| :5432 | | :5050 |
|
||||
+---------+ +----+----+ +-------+------+ +---------+
|
||||
| ^
|
||||
v |
|
||||
Laravel 12 +-----+------+
|
||||
Application | pgdata |
|
||||
| | volume |
|
||||
+----+----+ +------------+
|
||||
| FCM |
|
||||
| API |
|
||||
+---------+
|
||||
```
|
||||
|
||||
## Domain Context
|
||||
All four services run as Docker containers on a single host:
|
||||
|
||||
- **Location**: Sungai Kupang, Malaysia (Kedah region based on station IDs)
|
||||
- **Operator**: JPS (Department of Irrigation and Drainage), Malaysia
|
||||
- **Data source**: Remote telemetry stations transmit CSV data via FTP to a central server
|
||||
- **Data pipeline**: Python script (`autoscript/sidesdecode.py`) fetches FTP files, parses CSV, inserts into PostgreSQL, and triggers push notifications
|
||||
| Container | Image | Purpose |
|
||||
|-------------|-------------------------|--------------------------------------|
|
||||
| tckdev-app | php:8.2-fpm (custom) | Laravel application via PHP-FPM |
|
||||
| tckdev-web | nginx:stable-alpine | Serves static assets, proxies PHP |
|
||||
| tckdev-db | postgres:16 | Primary database |
|
||||
| tckdev-pgAdmin | dpage/pgadmin4 | Database administration UI |
|
||||
|
||||
A reverse proxy (outside Docker) terminates TLS and forwards traffic to the nginx container on port 80. The production URL is `https://sides.tck.com.my`.
|
||||
|
||||
## Data Pipeline
|
||||
|
||||
1. A Python script running outside Docker fetches CSV files from an external FTP server.
|
||||
2. The script parses rainfall and water level readings and inserts them into the PostgreSQL database.
|
||||
3. When a reading crosses a threshold, the script calls the `/api/alert` endpoint.
|
||||
4. `AlertController` resolves the appropriate FCM topic (e.g., `rainfall_danger`, `waterlevel_alert`) and pushes a notification to subscribed devices via `FcmService`.
|
||||
|
||||
FCM topics are configured through environment variables:
|
||||
|
||||
- `FCM_TOPIC_RAINFALL_WARNING`
|
||||
- `FCM_TOPIC_RAINFALL_DANGER`
|
||||
- `FCM_TOPIC_WATERLEVEL_ALERT`
|
||||
- `FCM_TOPIC_WATERLEVEL_DANGER`
|
||||
|
||||
## Core Data Model
|
||||
|
||||
| Table | Purpose |
|
||||
|---------------|------------------------------------------------------------|
|
||||
| `station` | Sensor stations (ID, name, district, coordinates, type flags) |
|
||||
| `rainfall` | Rainfall readings per station with timestamp, hourly/daily/cumulative values |
|
||||
| `waterlevel` | Water level readings per station with alert/warning/danger thresholds |
|
||||
| `notification`| Alert history per station, type, and severity level |
|
||||
| `siren` | Siren activation events linked to stations |
|
||||
| `users` | User accounts with role-based access levels |
|
||||
|
||||
## User Roles
|
||||
|
||||
| Role | Access Level | Description |
|
||||
|------|-------------|-------------|
|
||||
| **Public** | Unauthenticated | View dashboard map with station data |
|
||||
| **User** | `access_level = 2` | View all monitoring pages, historical data, export reports |
|
||||
| **Admin** | `access_level = 1` | Full access including station management and user management |
|
||||
| Role | access_level | Access |
|
||||
|--------|-------------|---------------------------------------------------------|
|
||||
| Admin | 1 | Station management, user management, all data views |
|
||||
| User | 2 | Rainfall/water level/siren/notification views, profile |
|
||||
| Public | (none) | Public dashboard and station map only |
|
||||
|
||||
## High-Level Architecture
|
||||
Admin credentials are set through environment variables (`ADMIN_EMAIL`, `ADMIN_PASSWORD`) and seeded on first deployment via `DatabaseSeeder`.
|
||||
|
||||
```
|
||||
[Telemetry Stations] --CSV/FTP--> [FTP Server (myvscada.com)]
|
||||
|
|
||||
[Python Script (cron)]
|
||||
|
|
||||
v
|
||||
[PostgreSQL Database] <--data-- [sidesdecode.py] --alert--> [Laravel API]
|
||||
|
|
||||
v
|
||||
[Firebase FCM]
|
||||
|
|
||||
v
|
||||
[Mobile Devices]
|
||||
|
||||
[Laravel Web App] <--reads-- [PostgreSQL Database]
|
||||
|
|
||||
v
|
||||
[Web Browser] <--Leaflet Map, Charts, Tables-->
|
||||
```
|
||||
## Localization
|
||||
|
||||
## Application Name
|
||||
The application supports English (`en`) and Bahasa Malaysia (`bm`). Language files are stored in `src/lang/en/` and `src/lang/bm/`. Users can switch language through the `/locale/{locale}` route.
|
||||
|
||||
The application is registered as **SIDES** in Laravel config (`APP_NAME=SIDES`).
|
||||
## Key Application Features
|
||||
|
||||
## Bilingual Support
|
||||
- **Map Dashboard** -- Live station data (rainfall, water level, siren status) displayed on an interactive map.
|
||||
- **Rainfall Monitoring** -- Current readings, historical data, hourly graphs, and IDF threshold analysis with Excel export.
|
||||
- **Water Level Monitoring** -- Current readings, historical data, graphs, and Excel export.
|
||||
- **Siren Management** -- Siren activation tracking with PDF export of siren history.
|
||||
- **Notification Center** -- Separate views for rainfall, water level, and siren alerts with PDF export.
|
||||
- **Station Management** -- Admin CRUD for sensor stations.
|
||||
- **User Management** -- Admin CRUD for user accounts.
|
||||
- **CCTV Integration** -- CCTV feed links per station.
|
||||
|
||||
The application supports:
|
||||
- **English** (en) — default
|
||||
- **Bahasa Malaysia** (bm)
|
||||
## API Endpoints
|
||||
|
||||
Language files are stored in `src/lang/{en,bm}/` and toggled via `LocaleController` with session-based persistence.
|
||||
The application exposes a REST API (prefix `/api/`) consumed by the data pipeline and external integrations:
|
||||
|
||||
## Project Name Origin
|
||||
|
||||
The repository is named `tckdev` (likely **TCK Development**), referencing the organization running the SIDES system.
|
||||
| Method | Path | Description |
|
||||
|--------|-----------------------------|------------------------------------------|
|
||||
| GET | /api/station/current | Latest readings across all stations |
|
||||
| GET | /api/station/rainfall | Current rainfall data |
|
||||
| GET | /api/station/waterlevel | Current water level data |
|
||||
| GET | /api/station/notification | Today's notifications |
|
||||
| GET | /api/station/history | Notification history (last 3 days) |
|
||||
| GET | /api/station/siren | Current siren status |
|
||||
| GET | /api/station/siren/history | Siren history (last 3 days) |
|
||||
| POST | /api/login | API authentication |
|
||||
| POST | /api/alert | Trigger FCM push notification |
|
||||
|
||||
Reference in New Issue
Block a user