Documentation

PumpPilot is a centralized motor control platform with web dashboard, mobile app, API backend, MongoDB storage, and ESP32 edge devices.

Example: User starts motor from dashboard -> API updates state -> ESP32 polls and runs motor.

One backend (Next.js App Router API) serves two clients (Web + React Native). MongoDB stores users, queue, wallet, logs, and system state.

Flow: Web/Mobile -> /api/* -> Queue/Timer engines -> MongoDB -> ESP32 /api/esp32/poll

Each Admin is a tenant. Users are strictly bound to adminId. Queue, minute requests, and runtime decisions are tenant-scoped.

Admin Rahim users cannot affect Admin Q users or queue.

Master Admin: system-wide control. Admin: tenant control. User: motor operation only. Mobile and web both enforce role checks.

User cannot call admin recharge API; request returns 403.

UI layer (pages/screens), API routes, engine layer (queue/timer/loadshedding), and model layer (mongoose schemas) are separated for maintainability.

Minutes are updated according to actual session activity and current safety rules. When a run ends, the final balance is recalculated automatically. Recharge updates availableMinutes with audit logs.

A user starts a run, uses the pump, and then stops. The system updates the final balance automatically.

Per admin only one RUNNING entry is allowed. New requests become WAITING with position. Next user auto-starts when current ends.

User A RUNNING, User B starts -> WAITING #1.

Load shedding or device unavailability can force HOLD state, pause decrement, and keep remaining time intact for safe resume.

A RUNNING session moves to HOLD during interruption and resumes from the remaining time when conditions recover.

ESP32 or supported device polling keeps the physical motor state aligned with backend state through regular requests. Device status, load shedding, and readiness signals are continuously reported to the server.

Firmware handles network connection, periodic polling, RFID scan flow where applicable, JSON response parsing, and GPIO-based motor control decisions using motor status, load shedding, and device readiness.

RUNNING + safe conditions => motor output ON, otherwise safe OFF or HOLD behavior.

Use relay/contactor isolation, proper fuse/MCB, optocoupler path, and interlock rule (single active motor per admin) for safety.

Core collections: admins, users, queues, usage_history, minute_requests, mobile_sessions. Indexed by adminId/userId/date/position for fast reads.

Queue compound index adminId+position speeds waiting list reads.

REST endpoints are role-scoped: auth, motor, queue, admin actions, master actions, mobile endpoints, and ESP32 poll endpoint.

POST /api/motor/start, POST /api/motor/stop, GET /api/esp32/poll?adminId=...

Queue ordering and state transitions are controlled server-side. Optimistic UI is corrected by realtime polling to prevent drift.

Password hashing, JWT/session auth, role guards, suspend workflow, and protected mobile bearer token endpoints reduce abuse risk.

API routes return explicit JSON errors and devices fall back to safe motor-off or HOLD behavior depending on the current safety state and connection health.

If a device cannot confirm a safe RUNNING state, the motor stays OFF until normal conditions return.

Tenant-scoped queries, indexed reads, lightweight polling payloads, and decoupled engines support scaling to 100+ motors.

Web/API deploy on Vercel, MongoDB Atlas as database, ESP32 devices configured with hosted API URL, mobile app via Expo/EAS.

Validate env vars, auth roles, suspend behavior, queue correctness, hold/resume, balance update correctness, and ESP32 command response.

Planned: websocket/MQTT realtime, richer analytics, alerting, backup/restore tooling, and stronger device certificate security.