⛽ PumpAI — AI WhatsApp CRM & forecourt management for Pakistani petrol pumps
A full-stack web app for petrol-pump owners in Pakistan. It covers:
- WhatsApp CRM: an AI agent answers customers 24/7 in Roman Urdu, Urdu or English.
- Forecourt operations: POS, shifts, tanks, dips, tanker deliveries and prices.
- Khata (credit) management.
- Background automations: loss/fraud detection, stock-out prediction, payment reminders, win-back campaigns and the owner's daily WhatsApp brief.
It runs fully offline out of the box, using demo data, a built-in rule-based Roman Urdu bot and simulated WhatsApp. Add a Claude API key and WhatsApp Cloud API credentials to switch to the AI agent and live messaging.
Quick start
Selling / installing for a pump owner? See INSTALL.md (one-command install with domain and HTTPS, setup wizard, updates, backups). A demo can also be put on Vercel (import the repo; see INSTALL.md → Option 3).
cd pumpai
npm install
npm run dev # API on :4000, dashboard on http://localhost:5173
-
Sign in (password demo1234 for all four). After one email sign-in on a tablet, staff can sign in by tapping their name and a 4-digit PIN (demo PINs: admin 1111, manager 2222, salesman 3333, wholesale 4444):
| Login | Role | Access |
|---|
[email protected] | Admin (CEO) | Everything, including Users & Roles, Settings and khata credit limits |
[email protected] | Manager | Dashboard, WhatsApp inbox, customers & khata, orders, complaints, campaigns, stock, prices, alerts, automations |
[email protected] | Salesman | POS, their own shift, customer lookup/add and prices, at their assigned station only |
[email protected] | Wholesale Officer | Only the wholesale module: clients, supplies, returns, payments, dues and statements |
-
First run: a demo business is created automatically: 2 stations, 5 tanks, about 8 weeks of sales, 32 customers, khata and WhatsApp chats.
-
Reset the demo data: npm run seed.
-
Production: npm run build && npm start. The API serves the built dashboard on :4000. A Dockerfile is included.
-
Tests: npm test runs 121 end-to-end API tests covering the WhatsApp agent, shifts, khata, stock, prices, orders, campaigns, automations, the Meta webhook, role-based access, wholesale supply (including per-client margins that follow pump price changes), expenses, suppliers, reports (including exact stock reconciliation across periods), mid-shift price changes with meter settlement, shift handover (readings, gaps, cash expenses, shift report), and a full-circle test that follows one day from the salesman's sales, expenses and meter close through a tanker delivery and a wholesale supply to the manager's notification and the admin's today book, checking every figure against the tanks and the Reports page. Further suites cover PIN sign-in and lockout, sale undo, offline sales synced once at the old price, meter/invoice/bill photos, voice-to-sale parsing (English, Roman Urdu, Urdu), khata receipts, monthly bill links, wholesale messages, QR cards, staff accounts, the cash book, tanker orders, dip charts, the midnight day close, owner questions on WhatsApp, the shop POS, vehicle limits, loyalty payments, licences, checklists, attendance and payroll cuts, owner insights (health score, staff risk, P&L, statement reconciliation, price planner, tank gain/loss), customer portal, khata hold and late charge, government bills, bookings, backups and restore, two-person price approval and push subscriptions, the stock register, coupons, wallets, ratings, the TV rate board, WhatsApp approvals, commission, monthly fixed costs and utility bills, tanker shortage claims, depot comparison, sales tax and withholding, bank statement reconciliation, the general ledger export, staff loans, salary slip PDFs, training records and daily coaching, the first-run setup wizard, branding, integrations set from the app, the audit log and the machines register.
Requires Node.js 22+ (uses the built-in node:sqlite, so there is no database server to install).
Features
| Area | What it does |
|---|
| WhatsApp AI agent | Claude with tools: live prices, khata balance and statement, payment links (JazzCash/Easypaisa/Raast), bulk diesel/petrol order booking with a credit check, complaints with tickets, station finder, loyalty points, opt-out (STOP), and hand-off to a human. It mirrors the customer's language. |
| Inbox | WhatsApp-style shared inbox with live updates (SSE). Take over or hand back any chat. An AI "draft reply" copilot. A simulator that runs the real webhook pipeline. |
| CRM | Customers, vehicles and fleets, AI segments (VIP, Regular, At risk, New, Fleet, Agri), churn probability, credit-risk score, loyalty points (1 per Rs 100). |
| Khata | Credit limits enforced at sale time, ledger, payment receipts on WhatsApp, automatic reminders with payment links. |
| Orders | Orders booked by the AI over WhatsApp. Confirm, dispatch and deliver steps each notify the customer. Delivery posts the sale and debits khata. |
| Add anything, from one place | An "+ Add new" button in the sidebar (and tiles on the dashboard) lets the admin add a khata account (police, school, govt office, hospital, fleet, farmer, business) with its vehicles and credit limit, a customer, supplier, wholesale client, station, tank with nozzles, staff user or expense category; managers get the items their role allows. New items appear immediately for everyone who uses them, e.g. a new khata account shows up in the salesman's POS marked NEW, and the right people are notified in-app: salesmen for new/closed khata accounts, new vehicles and new tanks at their station; managers for new customers, suppliers and stations; wholesale officers for new wholesale clients. Stations and tanks are also managed under Settings. |
| Salesman POS | A big-button, colour-coded, English + Urdu screen built for tablets and phones, usable with little reading: tap the fuel (Petrol / Hi-Octane / Diesel with today's rate), enter rupees or litres on a large keypad or quick buttons, tap the payment (Cash, Easypaisa, JazzCash, Card, Raast or Khata), then Save. A full-screen green tick confirms each sale. The side panel shows cash in hand that should be there, total sales and the last sales. It asks to start the shift first and pauses after a price change until confirmed. |
| Institutional khata | Credit accounts for police stations, schools, government offices and hospitals (alongside fleets, farmers and businesses). On the POS the salesman picks the account from big picture cards, taps the vehicle (e.g. police mobile) and types the slip / parchi number. Every entry keeps the litres, , amount, vehicle, slip and station, so the monthly (date range, print, Excel) shows exactly what was given and at what price, with running balance and totals per fuel. Salesmen never see account balances, only "near limit" / "limit full". |
Automations
| Job | Schedule | Action |
|---|
| AI customer scoring | daily 02:00 | Segments, churn score and credit-risk score |
| Loss & fraud detection | every 30 min | Dip variance, short deliveries, cash shortages (z-score per attendant), sales drops. Sends critical alerts to the owner on WhatsApp. |
| Tank stock-out prediction | hourly | Alerts and a suggested tanker order before the reorder level is reached |
| Khata reminders | daily 11:00 | Balance plus payment link, at most once per 3 days per customer |
| AI win-back campaign | Mondays 12:00 | AI-written offer to customers at risk of churning (opted-in only) |
| Owner's daily brief | daily 21:00 | Sales, cash/digital/khata, stock, alerts and forecast, sent on WhatsApp |
| Day close | daily 00:05 | Locks the previous day and sends the owner its report and link |
| Monthly bills | 1st of the month 09:00 | Khata bills and wholesale statements with a printable link |
| Licence & certificate expiry | daily 09:00 | Reminders 30/7/1/0 days before and weekly after expiry |
| Daily checklist follow-up | 12:00 and 20:00 | Managers told which daily checks are not done |
| Attendance follow-up | hourly | Staff not checked in an hour after duty time |
| Weekly staff risk | Mondays 10:00 | Risk score per salesman to the owner |
| Overdue khata hold | daily 08:00 | Accounts with no payment for N days put on hold |
| Late-payment charge | 1st of the month 08:00 | Only when a percent is set; never institutions |
| Booking reminders | every 15 min | WhatsApp an hour before each booking |
| Oil change due | daily 10:30 | Reminder 3 months after the last oil change |
| Nightly backup | daily 02:30 | Full database copy, last 14 kept |
| Monthly fixed expenses | daily 07:00 | Rent, guard, internet… booked on their day of the month |
| Weekly salesman leaderboard | Mondays 09:00 |
Architecture
WhatsApp users ─► Meta Cloud API ─► /webhooks/whatsapp ─┐
Dashboard (React + Vite + Tailwind) ─► /api (Express) ──┼─► services (sales, khata, stock, alerts)
├─► AI agent (Claude tool loop | rule-engine fallback)
├─► analytics (forecast, anomalies, scoring)
├─► automations (node-cron, Asia/Karachi)
└─► SQLite (node:sqlite, WAL)
pumpai/
├── server/src
│ ├── index.ts Express app, auth, static hosting
│ ├── db.ts / seed.ts schema + demo data
│ ├── services.ts sales, khata, prices, alerts (business rules)
│ ├── ai/agent.ts Claude agents: WhatsApp, Ask-AI, campaign writer
│ ├── ai/tools.ts customer-scoped agent tools
│ ├── ai/businessTools.ts read-only analytics tools for the owner
│ ├── ai/fallback.ts offline Roman Urdu intent engine
│ ├── ai/analytics.ts forecasting, anomaly detection, scoring, KPIs
│ ├── automation/ scheduled jobs
│ ├── whatsapp/cloud.ts Cloud API send (24h window → template), webhook parse, signature check
│ └── routes/ operations, crm, whatsapp, insights, users, wholesale, expenses, suppliers, reports
└── web/src/pages Dashboard, Inbox, Customers, Khata, Orders, Complaints, Campaigns,
POS, Shifts, Stock, Prices, Wholesale, Expenses, Suppliers, Reports, Alerts, Automations, Users, Settings
Going live
-
Claude. Set ANTHROPIC_API_KEY. The default model is claude-opus-5-5 at AI_EFFORT=low, which suits chat. Server-side refusal fallbacks are enabled. If the API fails, the bot falls back to the rule engine so it never goes silent.
-
WhatsApp Cloud API. In Meta Business Manager, create an app and add WhatsApp. Then:
- Set
WA_TOKEN, WA_PHONE_NUMBER_ID, WA_APP_SECRET and WA_VERIFY_TOKEN.
- Point the webhook at
https://<your-domain>/webhooks/whatsapp and subscribe to messages.
- Get a utility template approved, named
general_update, with a body of {{1}}. It is used automatically for messages sent outside the 24-hour customer-service window.
-
Payments. Set PAYMENT_LINK_BASE to your JazzCash/Easypaisa/Raast payment-link endpoint. Mark payments as received from the customer page; this sends the customer an automatic WhatsApp receipt.
-
Owner number. In Settings, enter the owner's WhatsApp number for alerts, the daily brief and the day-close report. Messages from this number (and from admins/managers whose number is saved) are answered by the business assistant instead of the customer bot.
-
Public URL. Set PUBLIC_URL to your domain so bill and day-report links in WhatsApp messages open correctly.
-
Prices. The seeded prices are demo values. Enter the current government-notified prices on the Prices page.
-
Backups. Backups go to data/backups (or BACKUP_DIR). Download one regularly and keep it off the server.
-
Phone alerts. Optional: set VAPID_PUBLIC_KEY / VAPID_PRIVATE_KEY; otherwise keys are created once and stored in the database. Push needs HTTPS.
See .env.example for every option.
Roadmap ideas
- WhatsApp voice notes from customers (Urdu speech to text)
- Hardware (pending until the equipment arrives): tank gauge probes, forecourt controller, CCTV number-plate reading, tanker GPS, generator/electricity meters
- FBR invoice integration
- PostgreSQL and multi-tenant SaaS billing
