Production-structured automation platform for Linux (Ubuntu 24.04+) using:

• Backend: Node.js + TypeScript + Express + whatsapp-web.js + SQLite
• Frontend: Next.js 14 (App Router) on frontend-next/
• Runtime: local, single-user cockpit with queue, rules, scheduler, activity feed, and settings

Architecture

Next.js UI (3001)
        ↓
Express API-only backend (3000)
        ↓
Wpify Engine + Queue + Rule Engine + Scheduler + SQLite

• Backend is API-only (no static frontend serving).
• Frontend runs independently and consumes backend APIs via NEXT_PUBLIC_API_URL.

Features

• WhatsApp Web integration via whatsapp-web.js
• Persistent session auth via LocalAuth (./sessions)
• Terminal QR rendering for first login
• Auto reconnect + manual reconnect endpoint
• API key authentication (x-api-key)
• Rate-limited send endpoint
• Reliable message queue (p-queue, concurrency 1, retries, delay)
• Rule engine:
  • Triggers: keyword, exact_match, sender
  • Actions: reply, forward_to_number
  • Priority, tags, trigger count, last-triggered metadata
• Scheduler:
  • schedule/list/delete
  • statuses: pending, executed, failed
• Activity logging + timeline feed
• Dashboard metrics + 24h activity chart
• Runtime settings persistence in SQLite
• Modern dark Next.js cockpit UI + splash landing
• CLI sender utility

Project Structure

.
├── src/
│   ├── server.ts
│   ├── routes.ts
│   ├── whatsapp.ts
│   ├── messageQueue.ts
│   ├── database.ts
│   ├── ruleService.ts
│   ├── schedulerService.ts
│   ├── activityService.ts
│   ├── metricsService.ts
│   ├── settingsService.ts
│   ├── middleware/authMiddleware.ts
│   ├── logger.ts
│   └── cli.ts
├── assets/                # repository branding and logo files
├── frontend-next/         # active frontend (Next.js 14)
├── sessions/              # WhatsApp LocalAuth session data
├── data/                  # SQLite DB
└── README.md

API Endpoints

Public:

• GET /status

Protected (x-api-key required):

• GET /health
• POST /send
• GET /dashboard/summary
• GET /dashboard/activity-24h
• GET /activity
• GET /rules
• POST /rules
• PUT /rules/:id
• DELETE /rules/:id
• GET /scheduled-messages
• POST /scheduled-messages
• DELETE /scheduled-messages/:id
• GET /settings
• PUT /settings
• POST /whatsapp/reconnect

Environment Configuration

Backend .env:

PORT=3000
WA_HEADLESS=false
API_KEY=change_this_key
SEND_DELAY_MS=1000
RATE_LIMIT_WINDOW_MS=60000
RATE_LIMIT_MAX=20
SCHEDULER_POLL_MS=5000
FRONTEND_ORIGIN=http://localhost:3001
API_BASE_URL=http://localhost:3000

Frontend frontend-next/.env.local:

NEXT_PUBLIC_API_URL=http://localhost:3000
NEXT_PUBLIC_API_KEY=change_this_key

NEXT_PUBLIC_API_KEY must match backend API_KEY.

Run (Development)

From repo root:

1. Backend

npm install
npm run dev

2. Frontend (new terminal)

npm run frontend:dev

Open:

• UI: http://localhost:3001
• API status: http://localhost:3000/status

Build

npm run build
npm run frontend:build

CLI Usage

npm run cli -- --to 923XXXXXXXXXX --msg "Hello from CLI"

Notes

• First WhatsApp auth requires scanning QR in terminal.
• Session is persisted; QR is not required again unless session is reset.
• The old archived Vite frontend is intentionally kept outside this repo.