Sustainability Hackathon, 2025

BlueWatch NI is a full-stack web application designed to transform raw government water quality data and citizen-generated reports into actionable alerts across Northern Ireland. By collapsing decades of time-series measurements into the latest monitoring station snapshots, BlueWatch NI delivers a clear, performant map the helps everyone make informed decisions about water safety and environmental health.

BlueWatch NI was inspired by the specification provided for the 2025 Sustainability Hackathon: Water, hosted by Queen's University Belfast. This solution was not submitted for the hackathon.

Table of Contents

• Background & Theoretical Motivation
  • The Problem
  • Key Features
  • Datasets & OpenData NI
  • How It Works
  • Why It Matters
• System Architecture
  • Backend Services
  • Frontend
  • Communication
  • Deployment
• Project Structure
• How to Run
• API Endpoints
• Next Steps & Planned Enhancements
• License

---

🌊 Background & Theoretical Motivation

BlueWatch NI: Real-time Water Quality Insights for Northern Ireland

The Problem

Northern Ireland's water resources face mounting and interconnected problems:

• Climate-driven flooding threatens homes, infrastructure, and agriculture
• Pollution events degrade river, lake, and drinking-water quality
• Data inaccessability — public water dataets exist but aren't actionable for citizens or small businesses
• Lack of community feedback loops means on-the-ground observations go unheard

Our Solution: BlueWatch NI

BlueWatch NI is a web platform that fuses live government water-quality data and hydrological dat with crowd-sourced reports to deliver real-time alerts on water quality and flood risk.

Key Features

• Latest Reading Aggregation: Collapses 140,000+ historical measurements into a single, up‑to‑date data point per monitoring station.
• Water-Quality Risk Engine: Applies configurable thresholds (e.g., DO < 5) to flag “high risk” conditions and log alerts.
• REST API Endpoints:
  • GET /api/aggregate returns { lastAggregationTime, aggregatedData } for map visualization.
  • GET /api/report returns all user‑submitted reports.
• Interactive Map Visualisation: Google Maps integration that plots color‑coded circles for each station and markers for user reports.
• Demo-Mode Performance Cap: Environment‑driven DEMO_FEATURE_LIMIT to restrict plotted stations (e.g., 200) for smooth demos.
• Secure Key Injection: Google Maps API key injected via EJS templates from .env, with referrer restrictions for added security.
• Containerised Deployment: Docker & Docker Compose configuration ensures consistent setup across development and production.

Datasets & OpenData NI

• River Water Quality Monitoring (1990-2018): GeoJSON feature collection of river-monitoring station readings (DO, pH, etc.), used end-to-end for aggregation, risk evaluation, and map plotting.

Additional OpenData NI water datasets (e.g. lakes, private supplies, protected areas) may be incorporated in future enhancements.

How It Works (in Theory)

1. Data Ingestion: Scheduled tasks fetch GeoJSON from OpenData NI.
2. Latest Reading Aggregation: Collapses all time-series samples into the most recent reading per station.
3. Risk Engine Evaluation: Applies threshold rules (DO, pH, contaminants) to identify “high risk” sites and triggers alerts.
4. Notification Dispatch: Logs alerts in-memory (with extension points for email, push, or external channels).
5. API Exposure: Provides RESTful endpoints for aggregated data and user reports.
6. Frontend Visualisation: EJS-backed page injects the Google Maps API key and runs map.js to render circles and markers.

Why It Matters

• Protects Public Health: Surfacing water-quality hazards in real time helps users avoid contaminated water.
• Mitigates Flood Risks: Early, localized flood warnings reduce property damage and enhance preparedness.
• Empowers Communities: Crowdsourced reporting and open data transparency enable grassroots engagement.
• Supports Environmental Resilience: Data-driven insights inform policy decisions and sustainable resource management.

---

🏗️ System Architecture

BlueWatch NI is structured as a modern, modular, containerised web application, enabling easy development, testing, and scaling.

Backend Services

• waterDataService: Fetches, caches, and filters GeoJSON data from OpenData NI at regular intervals.
• dataAggregator: Aggregates the latest reading per station, evaluates water-quality risk, and maintains in-memory data structures.
• alertService: Receives risk alerts from the aggregator and logs or dispatches notifications
• reportService: Handles creation, validation, and retrieval of user-submitted reports.
• aggregationRoutes & reportRoutes: Express routers and controllers exposing RESTful endpoints.

Frontend

• EJS: index.ejs serves the base HTML and injects environment-configured variables
• Map Logic: map.js implements Google Maps integration, rendering color-coded circles for stations and markers for reports.
• Static Assets: Served via Express middleware under /assets and /scripts for CSS and JavaScript.

Communication

• RESTful HTTP: All frontend-backend interactions use JSON payloads over HTTP requests to the API routes.
• Stateless Services: No shared process memory beyond in-memory caches.

Deployment

• Docker & Docker Compose: The application runs via Docker and Docker Compose enabling both development and deployment.
• Environment Configuration: Uses .env for secrets. 9 CI/CD Ready: Can integrate with GitLab CI or GitHub Actions for automated builds, tests, and deployment.

---

📁 Project Structure

bluewatch-ni/
    client/
        assets/
            style.css
        scripts/
            map.js
        views/
            index.ejs
    src/
        app.js
        server.js
        config/
            config.json
        controllers/
            aggregatorController.js
            reportController.js
            waterController.js
        routes/
            aggregateRoutes.js
            reportRoutes.js
            waterRoutes.js
        services/
            alertService.js
            dataAggregator.js
            reportService.js
            riskEngineService.js
            waterDataService.js
    tests/
        ...Unit & Integration Tests...
    .env
    .gitlab-ci.yml
    docker-compose.yml
    Dockerfile
    package.json
    README.md

---

🚀 How to Run

Prerequisites

• Docker & Docker Compose

Clone the Repository

git clone https://gitlab.com/BHarris02/bluewatch-ni.git
cd bluewatch-ni

Set Up Environment Variables

Copy the example environment file and update it with the required API keys, etc.

cp .env.example .env

Build and Run the System

docker-compose up --build

The application will be available at http://localhost:3000

Shutting Down the System

To stop and remove the container, press CTRL+C in your terminal and then run:

docker-compose down

Troubleshooting

• Ensure all required environment variables are set in your .env file, and that the .env file is located at the project root.
• If port 3000 is already in use, stop other processes or change the port in docker-compose.yml
• For other issues, check the container logs:

docker-compose logs <bluewatch-api>

---

API Endpoints

Below are the primary RESTful endpoints exposed by the BlueWatch NI API. No authentication is required for demo/hackathon use.

GET /api/aggregate

• Description: Returns the timestamp of the latest aggregation and an array of the most recent water-quality features, one per station.
• Parameters: None
• Example:

  curl http://localhost:3000/api/aggregate

• Response:

  {
  "lastAggregationTime": "2025-07-15T12:34:56.789Z",
  "aggregatedData": [
      {
      "properties": {
          "Station_Name": "River X",
          "DO_MGL": 7.5,
          "PH": 7.2
      },
      "geometry": { "type": "Point", "coordinates": [-6.1, 54.6] }
      },
      // …more features
  ]
  }

GET /api/report

• Description: Retrieves all user-submitted reports of pollution, flooding, or hazards.
• Parameters: None
• Example:

  curl http://localhost:3000/api/report

• Response:

  [
  {
      "lat": 54.62,
      "lng": -5.90,
      "type": "pollution",
      "comment": "Oil slick observed",
      "timestamp": "2025-07-14T09:20:00.000Z"
  },
  // …more reports
  ]

---

Next Steps & Planned Enhancements

• UI Filtering: Station, basin, and date‑range selectors on the map interface.
• Report Analytics: Query parameters for /api/report (type, date range) and corresponding UI controls.
• Clustering & Heatmaps: Marker clustering and density heatmaps for large datasets.
• Persistence & Authentication: Integrate a database and user authentication for secured report submissions.

---

License

This project is licensed under the terms of the MIT License. See the LICENSE file for details.