sides/docs/02-ARCHITECTURE.md

Architecture

Technology Stack

Layer	Technology	Version
Backend	Laravel (PHP)	12.x
PHP	PHP-FPM	8.2
Frontend	Blade Templates + Alpine.js	3.x
CSS	Tailwind CSS + Bootstrap 5.3	3.x / 5.3
Charts	Custom JS (Chart.js via graph.js)	—
Maps	Leaflet.js	1.9.4
Build Tool	Vite	7.x
Database	PostgreSQL	15
Cache/Session	Database (via Laravel)	—
Queue	Database (via Laravel)	—
Containerization	Docker + Docker Compose	3.9
Web Server	Nginx	stable-alpine
PDF Generation	barryvdh/laravel-dompdf	3.1
Excel Export	maatwebsite/excel	3.1
Push Notifications	Firebase Cloud Messaging (FCM) via Google Auth	1.49
Date Picker	Flatpickr	4.6
Auth Scaffold	Laravel Breeze	2.3
Data Pipeline	Python (psycopg2, ftplib)	3.x

Container Architecture

The application runs in 5 Docker containers defined in docker-compose.yml:

┌──────────────────────────────────────────────────────────┐
│                    Docker Network: tckdev_net             │
│                                                          │
│  ┌─────────┐   ┌─────────┐   ┌──────────┐              │
│  │  web    │   │  app    │   │ postgres │              │
│  │ (nginx) │──>│ (PHP-FPM│──>│   (DB)   │              │
│  │ :80     │   │  :9000) │   │  :5432   │              │
│  └─────────┘   └─────────┘   └──────────┘              │
│                                                          │
│  ┌─────────┐   ┌─────────┐                              │
│  │ pgAdmin │   │ adminer │                              │
│  │ :5050   │   │ :6060   │  (DB management tools)       │
│  └─────────┘   └─────────┘                              │
└──────────────────────────────────────────────────────────┘

Container Details

Container	Image	Port	Purpose
tckdev-app	Custom (PHP 8.2-FPM + Composer 2.3 + Node.js)	9000 (internal)	Laravel application
tckdev-web	nginx:stable-alpine	80	Reverse proxy & static files
tckdev-db	postgres:15	5432	PostgreSQL database
tckdev-pgAdmin	dpage/pgadmin4	5050	Database management UI
tckdev-adminer	adminer	6060	Lightweight DB management UI

Request Flow

Browser --> Nginx (:80) --> PHP-FPM (:9000) --> Laravel Router
                                                    |
                                      ┌─────────────┼─────────────────┐
                                      v             v                 v
                                  Web Routes    API Routes        Auth Routes
                                  (web.php)    (api.php)         (auth.php)
                                      |             |                 |
                                      v             v                 v
                                Controllers    Api/Controllers    Breeze Controllers
                                      |             |
                                      v             v
                                DB::raw() SQL   DB::raw() SQL
                                      |             |
                                      v             v
                                  PostgreSQL    PostgreSQL
                                      |
                                      v
                                Blade Views --> HTML Response

Middleware Stack

Middleware	Route Group	Purpose
auth	Web (protected)	Require authenticated session
admin	Admin routes	Require access_level = 1
LocalizationMiddleware	All web routes	Set locale from session (en/bm)
guest	Auth routes (login/register)	Redirect away if already authenticated

Database Design

Core Tables

┌─────────────┐       ┌──────────────┐
│   station   │       │    users     │
│─────────────│       │──────────────│
│ stationid*  │       │ id*          │
│ name        │       │ name         │
│ district    │       │ email        │
│ lng, lat    │       │ password     │
│ mainriverbasin│     │ access_level │
│ subriverbasin│      │ is_blocked   │
│ rainfall    │       │ login_attempts│
│ waterlevel  │       └──────────────┘
│ siren       │
│ cctv_link   │
└──────┬──────┘
       │
       │ (stationid FK via application logic, not DB constraint)
       │
  ┌────┼────────────┬──────────────┐
  v    v            v              v
┌──────────┐ ┌────────────┐ ┌───────────┐
│ rainfall │ │ waterlevel │ │   siren   │
│──────────│ │────────────│ │───────────│
│ id*      │ │ id*        │ │ id*       │
│ stationid│ │ stationid  │ │ stationid │
│ timestamp│ │ datetime   │ │ stationtype│
│ anncum   │ │ waterlevel │ │ active_time│
│ daily    │ │ alert      │ │ level     │
│ hourly   │ │ warning    │ └───────────┘
│ currentrf│ │ danger     │
│ battery  │ └────────────┘
└──────────┘
       │
       v
┌──────────────┐
│ notification │
│──────────────│
│ id*          │
│ stationid    │
│ timestamp    │
│ stationtype  │  (1=rainfall, 2=waterlevel, 3=siren)
│ level        │  (Normal, Alert, Warning, Danger)
│ active_time  │
└──────────────┘

Station Types

The station table uses boolean flags to indicate which monitoring types each station supports:

• rainfall = 1 — Station has rainfall monitoring
• waterlevel = 1 — Station has water level monitoring
• siren = 1 — Station has a warning siren

Foreign Key Note

There are no database-level foreign keys between station and the data tables. Relationships are maintained at the application level via stationid column matching.

Laravel Standard Tables

The application also uses standard Laravel tables:

• users — Authentication and authorization
• password_reset_tokens — Password reset flow
• sessions — Database-backed sessions
• cache, cache_locks — Database cache store
• jobs, job_batches, failed_jobs — Database queue

Authentication & Authorization

• Web auth: Laravel Breeze (session-based, Blade views)
• API auth: Custom token-less login via Api\AuthController (returns user info, no token generation)
• Admin access: Controlled by AdminMiddleware checking access_level === 1
• User blocking: Users can be blocked via is_blocked flag (though no middleware enforces it currently)