# 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

```bash
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/`](docs/):

| Document | Description |
|----------|-------------|
| [01-OVERVIEW](docs/01-OVERVIEW.md) | Project overview, purpose, and high-level architecture |
| [02-ARCHITECTURE](docs/02-ARCHITECTURE.md) | Technology stack, container layout, request flow, middleware |
| [03-DEPLOYMENT](docs/03-DEPLOYMENT.md) | Docker Compose deployment, reverse proxy setup, production checklist |
| [04-DATA-PIPELINE](docs/04-DATA-PIPELINE.md) | Python autoscript, FTP ingestion, CSV parsing, alert triggers |
| [05-FEATURES](docs/05-FEATURES.md) | User-facing features, routes, and access control |
| [06-DATABASE](docs/06-DATABASE.md) | PostgreSQL schema, tables, relationships |
| [07-API](docs/07-API.md) | REST API reference for station data and push notifications |
| [08-CONFIGURATION](docs/08-CONFIGURATION.md) | 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
```