PumpLink is an open-source backend service written in Golang that enables remote, scheduled, authenticated control of motor pumps (or any device) via MQTT and REST APIs. It automates decades-old motor pumps turning them into IoT-ready, controllable devices. 

Backend Language & Frameworks

  • Golang (Go): Core programming language used for the entire backend service.

  • Gin Web Framework: Fast and lightweight HTTP router for building REST APIs.

Security & Authentication

  • JWT Authentication: Secures all protected endpoints (login, device control, schedules).

  • Role-Based Access Control: Admin role with elevated privileges.

  • Password hashing for secure credential storage.

Core Features

User Management

  • Registration & Login: HTTP endpoints for user account creation and JWT token issuance. 

  • JWT Protected Endpoints: Auth middleware guards user-specific actions.

Device Activation & Control

  • POST /api/activate-device: Queue system accepts device activation requests with duration.

  • Queue & Async Processing: Activates devices in the background with thread-safe quotas.

  • Device State Tracking: ON/OFF state stored in database with logs. 

Session & Logging

  • Device Sessions: Sessions track periods when a device is ON (start/end, duration).

  • Device Logs: All ON/OFF events logged for audit-ability.

Scheduling

  • Scheduled Activations: Users can schedule future activations.

  • Priority Queue Scheduler: Uses a min-heap (priority queue) to trigger activations at correct times while maintaining concurrency safety.

MQTT Integration

  • MQTT Broker connection for real-time device control/commands.

  • Centralised topic definitions & helper services. 

Real-Time Updates

  • WebSocket Service: Real-time device status broadcast to clients authenticated via JWT.

  • Ensures connected clients get instant device status updates on change. 

Admin & Safety Controls

  • Force Shutdown API: Admins can stop running device activations instantly.

  • This supports safety & override capability if needed. 

Push Notifications

  • Integration with Expo Push for mobile client notifications when devices activate.

  • Includes token registration and deduplication logic. 

Database

  • PostgreSQL as the primary data store.

  • Uses GORM ORM for database interactions. GitHub

  • ERD diagram included (ERD.png) showing relationships: users, devices, sessions, logs.

Unique Technical Benefits

✔ Async control queue prevents blocking and supports safe concurrency.
✔ MQTT + REST + WebSockets blend real-time and structured control.
✔ Schedule + quota + safety overrides provide robust pump automation.
✔ Fully open source and modular for extension (UI apps, firmware).

How It Works (High-Level)

  1. User logs in → receives JWT

  2. Client sends device control (activate/schedule)

  3. Backend enqueues and processes requests asynchronously

  4. MQTT broker signals physical IoT device (pump controller)

  5. WebSockets notify UI clients of status updates