Documentation

System Overview

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.

High-Level Architecture

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

Multi-Tenant Isolation Model

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.

Role-Based Access Control (RBAC)

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.

Application Layer Design

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

Wallet Engine Architecture

Minutes are deducted on actual usage. Early stop returns unused minutes. Recharge updates availableMinutes with audit logs.

Set 10m, stop at 6m -> used 6, refund 4.

Smart Queue Engine Architecture

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 Engine Design

Load shedding forces HOLD state, pauses decrement, and keeps remaining time intact for safe resume.

RUNNING 8m -> HOLD due to power loss -> resume from 8m on recovery.

Device Synchronization Engine

ESP32 polling syncs physical state with backend state every 3-5 seconds. Local load-shedding pin can also be sent to server.

ESP32 Firmware Architecture

Firmware has WiFi/GPRS connect, poll loop, JSON parser, and motor GPIO decision logic using motorStatus + loadShedding.

RUNNING + no LS => GPIO HIGH, otherwise GPIO LOW.

Hardware Integration & Electrical Protection Design

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

Database Schema & Index Strategy

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.

API Architecture & Endpoint Design

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=...

Concurrency & State Management Strategy

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

Security Architecture

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

Error Handling & Fail-Safe Strategy

API routes use try/catch and explicit JSON errors. On failures, motor-safe fallback is OFF/HOLD depending on state.

ESP32 non-200 response => keep safe OFF output.

Scalability & Performance Strategy

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

Deployment Architecture

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

Production Validation Checklist

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

Future Upgrade & Expansion Roadmap

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