Files

root e22644b32b docs: rewrite README for SIDES project

Replace template boilerplate with project description, quick start,
documentation index linking to docs/, stack summary, and project structure.

2026-05-21 03:39:23 +08:00

2.6 KiB

Raw Blame History

SIDES

Sabo Integrated Debris Flow Monitoring and Early Warning System

Flood and debris flow early warning system for Sungai Kupang, Malaysia. Operated under Jabatan Pengairan dan Saliran (JPS) — the Malaysian Department of Irrigation and Drainage.

Monitors rainfall, water levels, and siren activations at remote telemetry stations with a real-time web dashboard, interactive map, and push notifications.

Quick Start

git clone <repo-url> && cd tckdev
cp .env.example .env          # Configure credentials
cp src/.env.example src/.env  # Configure Laravel
docker compose up -d --build

The app container automatically runs migrations, seeding, and asset building on first start. Access the dashboard at http://localhost.

Documentation

Full documentation is in docs/:

Document	Description
01-OVERVIEW	Project overview, purpose, and high-level architecture
02-ARCHITECTURE	Technology stack, container layout, request flow, middleware
03-DEPLOYMENT	Docker Compose deployment, reverse proxy setup, production checklist
04-DATA-PIPELINE	Python autoscript, FTP ingestion, CSV parsing, alert triggers
05-FEATURES	User-facing features, routes, and access control
06-DATABASE	PostgreSQL schema, tables, relationships
07-API	REST API reference for station data and push notifications
08-CONFIGURATION	Environment variables, Docker Compose config, Nginx, Laravel

Stack

Backend: Laravel 12 (PHP 8.2-FPM)
Database: PostgreSQL 16
Frontend: Blade + Alpine.js + Tailwind CSS + Leaflet.js
Push Notifications: Firebase Cloud Messaging
Data Pipeline: Python (psycopg2, ftplib)
Deployment: Docker Compose (nginx, php-fpm, postgres, pgadmin)

Project Structure

tckdev/
├── src/                    # Laravel application (bind-mounted into containers)
│   ├── app/Http/Controllers/
│   ├── database/migrations/
│   ├── routes/
│   ├── resources/views/
│   └── .env
├── autoscript/
│   └── sidesdecode.py      # Python data ingestion pipeline
├── docker/
│   ├── nginx/default.conf
│   └── entrypoint.sh
├── docs/                    # Documentation wiki
├── docker-compose.yml
├── Dockerfile
├── .env                     # Docker-level credentials
└── .env.example