gistfile1.txt

# ♻️ Zinga Waste Management API

[![Backend Engine](https://img.shields.io/badge/Engine-Node.js%20v20+-green.svg?style=for-the-badge&logo=node.js)](https://nodejs.org/)
[![Language](https://img.shields.io/badge/Language-TypeScript-blue.svg?style=for-the-badge&logo=typescript)](https://www.typescriptlang.org/)
[![Database](https://img.shields.io/badge/Database-PostgreSQL-blue.svg?style=for-the-badge&logo=postgresql)](https://www.postgresql.org/)
[![ORM](https://img.shields.io/badge/ORM-Sequelize-darkblue.svg?style=for-the-badge&logo=sequelize)](https://sequelize.org/)
[![Realtime](https://img.shields.io/badge/Realtime-Socket.io-black.svg?style=for-the-badge&logo=socket.io)](https://socket.io/)
[![Environment](https://img.shields.io/badge/Environment-Enterprise--Grade-orange?style=for-the-badge)](#)

The **Zinga Waste Management API** is a high-performance, enterprise-grade backend infrastructure designed to power modern urban waste collection, scheduling, geolocation tracking, and coordination services. Built with a robust **Node.js + Express + TypeScript** stack, it utilizes **PostgreSQL** alongside the spatial extension **PostGIS** for real-time routing, **Socket.io** for micro-second synchronization, **Cloudinary** for scalable media delivery, and a custom **daily-rotating logger** built for robust operational audits.

---

## 🏗️ System Architecture & Flow

The Zinga system implements a clean separation of concerns. Below is the communication flow between the primary components of the enterprise architecture:

```mermaid
graph TD
    %% Define styles
    classDef client fill:#f9f,stroke:#333,stroke-width:2px;
    classDef api fill:#bbf,stroke:#333,stroke-width:2px;
    classDef db fill:#bfb,stroke:#333,stroke-width:2px;
    classDef ext fill:#ffb,stroke:#333,stroke-width:2px;

    %% Primary Nodes
    AdminWeb["🖥️ Admin Dashboard (React/Web)"]:::client
    DriverMobile["📱 Driver App (Flutter/Mobile)"]:::client
    ExpressAPI["🚀 Express API Router (v1)"]:::api
    SocketIO["⚡ Socket.io Realtime Server"]:::api
    PostgresSQL["🗄️ PostgreSQL + PostGIS (Sequelize)"]:::db
    CustomLogger["📝 Custom Rotating Logger"]:::api

    %% Third Party Integration Nodes
    CloudinaryCDN["☁️ Cloudinary CDN"]:::ext
    MailgunSMTP["📧 Mailgun Mailer"]:::ext
    PDFGenerator["📄 PDFKit Report Engine"]:::api

    %% Interactions
    AdminWeb -->|REST Requests| ExpressAPI
    DriverMobile -->|REST Requests| ExpressAPI
    
    AdminWeb <-->|Websocket Sync| SocketIO
    DriverMobile <-->|Websocket Sync| SocketIO

    ExpressAPI -->|Read/Write Model Data| PostgresSQL
    ExpressAPI -->|Audit logs| CustomLogger
    ExpressAPI -->|Media Streams| CloudinaryCDN
    ExpressAPI -->|Trigger Alerts| MailgunSMTP
    ExpressAPI -->|Compile Statistics| PDFGenerator
```

---

## 🌟 Key Enterprise Features

### 🔑 1. Role-Based Access Control (RBAC) & Authentication
- Dual-path security framework supporting **Admin Portal** and **Driver / Customer Mobile clients** using industry-standard JSON Web Tokens (JWT).
- Access tokens expire daily, and secure, high-entropy refresh tokens are used for session preservation.
- Secure password hashing using `bcryptjs` with auto-adjusting salt rounds.

### 🗺️ 2. Dynamic Driver Geolocation & Spatial Queries
- Spatial query engine built on top of **PostGIS** to calculate real-time proximity and find nearby drivers within target radius points.
- Instant, non-blocking GPS update channels storing coordinates in a relational history table.

### 📅 3. Smart Bins & Collection Schedule Automation
- Structured group hierarchy (`Groups` ➡️ `Households`) to assign collection zones efficiently.
- Operational run lifecycle management (`CollectionRun`) supporting initialization, progress monitoring, exception catching, and run finalization.
- Support for QR-code scanner matching on bins via physical identifiers.

### 💬 4. WebSocket-Powered Realtime Coordination Hub
- Bi-directional micro-second latency synchronization layer utilizing **Socket.io**.
- Supports private grouping room channels, instant messaging, and coordination logs.

### 📊 5. Automated PDFKit Reports & QR Codes
- Generates dynamic, high-resolution operational reports in PDF using **PDFKit**.
- Embedded cryptographic-quality QR Codes created programmatically to pair and verify bin allocations.

### 💾 6. High-Performance Custom Rotating Logger
- Built-in `RotatingLogger` utilizing strict stream rotation boundaries (date-based daily rollover and file-size threshold caps).
- Protects disk storage against overflows while maintaining historical retention (auto-clean old indexes after configurable max logs boundary).

---

## 💻 Tech Stack Specification

| Category | Technology | Purpose |
| :--- | :--- | :--- |
| **Core Engine** | Node.js v20+, Express 5.x | High-throughput runtime environment and modern routing framework |
| **Language** | TypeScript v5.9+ | Static analysis, strict typing, interfaces, and clean compilation blocks |
| **Database** | PostgreSQL v16+, PostGIS | Relational transactions and precise geospatial operations |
| **ORM** | Sequelize, Sequelize-TypeScript | Strongly typed active-record mapping with decorator support |
| **Realtime** | Socket.io v4.8+ | Low-latency bi-directional event dispatching |
| **Storage CDN** | Cloudinary | Cloud-native media ingestion, optimization, and edge delivery |
| **Email SMTP** | Mailgun | Dynamic HTML notifications and verification routing |
| **Reporting** | PDFKit, Qrcode | Rich layouts, custom fonts, PDF exports, and QR code generations |
| **DevOps** | PM2, Nginx, Nodemon | Automated process management, reverse proxying, and dev hot-reloads |

---

## 📁 Repository Structure

```directory
zinga-api/
├── dist/                     # Compiled JavaScript assets (production-ready)
├── logs/                     # Auto-generated rotating application audit files
├── scripts/                  # DevOps, environment, and helper utilities
├── src/
│   ├── config/               # Database, Sequelize, and Cloudinary initialization
│   ├── controllers/          # Request handlers separated into Mobile and Admin namespaces
│   ├── middlewares/          # JWT protection, role validation, and CORS policies
│   ├── models/               # Sequelize-TypeScript decorator-based data models
│   ├── routes/               # Modular Express API endpoints grouped by Version (v1)
│   │   └── v1/
│   │       ├── admin/        # Admin dashboard controller routes (auth, driver schedules, reports)
│   │       └── mobile/       # Drivers and Customer API pathways
│   ├── seed/                 # Database seed templates (pickup reports, initial configurations)
│   ├── sockets/              # Socket.io event-listeners and real-time room routers
│   ├── utils/                # Rotating logs, helper utilities, and PDF/QR formatters
│   ├── app.ts                # Express application configuration and middleware hooks
│   └── server.ts             # Server entry point initializing DB and HTTP/WebSocket bindings
├── tsconfig.json             # TypeScript compilation settings
├── package.json              # Script directives, dependency mappings, and project metadata
└── DEPLOYMENT.md             # Production guide (PaaS and VPS setups)
```

---

## ⚙️ Configuration & Environment Variables

Copy `env-sample` to `.env` and fill out your local secrets:

```bash
cp env-sample .env
```

| Key Name | Default Value | Description |
| :--- | :--- | :--- |
| **PORT** | `3000` | Port where the server will bind its HTTP/WebSocket listeners |
| **NODE_ENV** | `development` | Runtime environment modifier (`development`, `staging`, `production`) |
| **JWT_ACCESS_SECRET** | *(Required)* | High-entropy secret key used to sign access JWT credentials |
| **JWT_REFRESH_SECRET**| *(Required)* | High-entropy secret key used to sign session preservation tokens |
| **JWT_ACCESS_EXPIRES_IN** | `1d` | Expiration window for standard authentication access tokens |
| **JWT_REFRESH_EXPIRES_IN**| `7d` | Expiration window for standard session preservation tokens |
| **DB_HOST** | `localhost` | Relational database IP or domain endpoint |
| **DB_PORT** | `5432` | Relational database TCP connection port |
| **DB_USERNAME** | `postgres` | Username authorized to write data on the target DB scheme |
| **DB_PASSWORD** | `postgres` | Password corresponding to the target database owner |
| **DB_NAME** | `zinga_db` | Relational schema workspace name |
| **CLOUDINARY_CLOUD_NAME** | *(Required)* | Cloudinary cloud profile identifier for asset ingestion |
| **CLOUDINARY_API_KEY** | *(Required)* | API Key authorized to push file uploads to the CDN storage |
| **CLOUDINARY_API_SECRET**| *(Required)* | Secret parameter authorizing secure CDN API calls |
| **LOG_DIR** | `logs` | Relative path where rotation logs will be structured |
| **LOG_MAX_SIZE_MB** | `10` | Size threshold in Megabytes before triggering logger rollover |
| **LOG_MAX_FILES** | `14` | Retention limit for historical rotation index files |
| **MAILGUN_API_KEY** | *(Required)* | Secure transactional API token for email execution |
| **MAILGUN_DOMAIN** | *(Required)* | Mailgun verified sandbox or custom routing domain |
| **MAILGUN_FROM_EMAIL** | *(Required)* | Outbound mail address shown to recipient clients |

---

## 🚀 Local Development Setup

### 📋 1. Prerequisites
- **Node.js**: `v20.x` or higher
- **PostgreSQL**: `v16` or higher
- **PostGIS Extension**: Enabled inside your database configuration environment

### 🔧 2. Installation & Bootstrapping

1. **Clone the repository and install packages**:
   ```bash
   git clone https://github.com/koolfreak/zinga-api.git
   cd zinga-api
   npm install
   ```

2. **Database Provisioning**:
   Configure a local PostgreSQL database and enable required UUID/GIS extensions.
   ```bash
   createdb zinga_db
   psql -d zinga_db -c 'CREATE EXTENSION IF NOT EXISTS "uuid-ossp";'
   psql -d zinga_db -c 'CREATE EXTENSION IF NOT EXISTS "postgis";'
   ```

3. **Populate Mock Seed Data**:
   Inject critical tables with mock templates (including pickup reports):
   ```bash
   npx ts-node src/seed/pickup_report_seed.ts
   ```
   *(Optional)* If sequence indices need synchronization after raw inserts, run:
   ```bash
   npx ts-node fix_db_sequence.ts
   ```

4. **Execution**:
   - **Local Hot-Reload** (Nodemon + ts-node compiles automatically on file save):
     ```bash
     npm run dev
     ```
   - **Production Compilation & Run**:
     ```bash
     npm run build
     ```
     ```bash
     npm start
     ```

---

## ⚡ Realtime Event Documentation (Socket.io)

Coordinate clients dynamically by binding to the Socket.io port (`http://localhost:3000` by default):

### 📥 Subscribed / Sent Events
* **`join_room`**: Let drivers, dispatchers, or customers bind to operational channels.
  * **Payload**: `{ roomId: string }`
* **`send_message`**: Transmit real-time messages within coordination rooms.
  * **Payload**: `{ roomId: string, message: string, senderId: string }`
* **`receive_message`**: Event broadcasted to rooms on receipt of an inbound transmission.

---

## 🛣️ API Endpoints Summary

### 👤 1. Authentication Routes

| Portal | Action | Method | Endpoint Path | Auth Required? |
| :--- | :--- | :--- | :--- | :--- |
| **Admin** | Register / Sign Up | `POST` | `/api/v1/admin/auth/register` | No |
| **Admin** | Login | `POST` | `/api/v1/admin/auth/login` | No |
| **Mobile**| Driver Sign Up | `POST` | `/api/v1/mobile/auth/register` | No |
| **Mobile**| Driver Sign In | `POST` | `/api/v1/mobile/auth/login` | No |

### 🛠️ 2. Admin Portal Operations

| Module | Action | Method | Endpoint Path | Auth Required? |
| :--- | :--- | :--- | :--- | :--- |
| **Dashboard**| Load statistics overview | `GET` | `/api/v1/admin/home` | Yes (JWT) |
| **Customers**| Get profile metrics | `GET` | `/api/v1/admin/customer` | Yes (JWT) |
| **Drivers** | Get profiles list | `GET` | `/api/v1/admin/driver` | Yes (JWT) |
| **Schedules**| Query collection shifts | `GET` | `/api/v1/admin/driver-schedule` | Yes (JWT) |
| **Pickups** | Query all pickup files | `GET` | `/api/v1/admin/pickup` | Yes (JWT) |
| **Bins** | Register & lookup smart bins | `GET` | `/api/v1/admin/bin` | Yes (JWT) |
| **Groups** | Query collection zones | `GET` | `/api/v1/admin/group` | Yes (JWT) |
| **Reports** | Compile dynamic PDF reports | `GET` | `/api/v1/admin/report` | Yes (JWT) |

### 📱 3. Driver Mobile Operations

| Module | Action | Method | Endpoint Path | Auth Required? |
| :--- | :--- | :--- | :--- | :--- |
| **Schedule** | Fetch assigned shifts | `GET` | `/api/v1/mobile/driver/schedule` | Yes (JWT) |
| **Groups** | Fetch assigned zones | `GET` | `/api/v1/mobile/driver/groups` | Yes (JWT) |
| **Geo** | Submit location telemetry | `POST` | `/api/v1/mobile/driver/location` | Yes (JWT) |
| **Geo** | Retrieve neighboring teams | `GET` | `/api/v1/mobile/driver/location/nearby` | Yes (JWT) |
| **Run** | Initiate collection route | `POST` | `/api/v1/mobile/driver/collection/:groupId/start` | Yes (JWT) |
| **Run** | Conclude collection route | `POST` | `/api/v1/mobile/driver/collection/:runId/end` | Yes (JWT) |
| **Bins** | Log QR code bin scan | `GET` | `/api/v1/mobile/driver/bin/:qrCode` | Yes (JWT) |
| **Collect** | Execute normal bin empty | `POST` | `/api/v1/mobile/driver/collect` | Yes (JWT) |
| **Exceptions**| Register collection issue | `POST` | `/api/v1/mobile/driver/collect/issue` | Yes (JWT) |
| **Uploads** | Upload proof of issue image | `POST` | `/api/v1/mobile/driver/image-upload` | Yes (JWT) |

---

## 🔒 Security Best Practices Implemented

1. **Helmet & Security Headers**: Integrated `helmet` middleware to prevent common vulnerabilities (XSS, Clickjacking, MIME sniffing, and clickjacking) by dynamically setting HTTP response headers.
2. **CORS Validation**: Fine-grained Cross-Origin Resource Sharing control configured globally to protect route resources.
3. **Structured Request Logging**: Morgan integration coupled with custom log rotation ensures all requests are recorded securely without bloating process memory.
4. **Token Encryption**: Multi-layer JWT structures featuring distinct, strong verification algorithms for access and refresh layers.

---

## 📦 Production Deployment

For step-by-step instructions on deploying the Zinga API to production, please read [DEPLOYMENT.md](file:///Users/eman/Projects/Zinga/zinga-api/DEPLOYMENT.md).

- **PaaS (Render, Railway, Heroku)**: Recommended for automated builds (`npm install && npm run build`), easy environment variable routing, SSL termination, and native support for Socket.io WebSockets.
- **VPS (Ubuntu, AWS EC2, DigitalOcean)**: Configured using a robust system architecture powered by **PM2** process managers and an **Nginx** reverse proxy, ensuring seamless traffic handling, SSL setup via Let's Encrypt, and optimized WebSocket upgrades.

---

## 👥 Authors & Contributors
- **Eman Nollase** — Lead Architect & Creator

---

## 📄 License
This system is licensed under the **ISC License**. For terms of use, see `package.json`.