Stage 5a: MiniWhatsApp — Local Test Harness 📱

A standalone WhatsApp-lookalike web app that talks to Orbita over HTTP + WebSocket, so we can iterate on real external messaging without touching Meta's API.

Status: ✅ Complete Lives at: /Users/sajithmr/1box/miniwhatsapp/ (sibling project, NOT inside orbita-core) Plugin: orbita-core/plugins/whatsapp-mock.plugin.tsPort: 4000 (miniwhatsapp) ↔ 3210 (orbita)

Why This Exists

The hardest part of "real WhatsApp" is iteration speed. You can't fluently debug Meta's Business API — slow approvals, template rules, 24-hour windows, webhooks behind public URLs. So we built a pretend WhatsApp that speaks the same shape:

• Users register with a phone number (any string, no OTP)
• Send messages browser-to-browser via WebSocket
• Orbita sends outbound via POST /api/send
• Orbita receives inbound via webhook POST /wa-webhook

Swap the plugin's URL later → real WhatsApp works. Core unchanged.

Architecture

┌─────────────────────┐         ┌───────────────────────┐
│  MiniWhatsApp :4000 │◄────WS─►│  Browser chats        │
│  - server.ts        │         │  - public/index.html  │
│  - data.json (disk) │         │  - public/admin.html  │
└──────────┬──────────┘         └───────────────────────┘
           │
           │ POST /wa-webhook    (inbound message)
           ▼
┌─────────────────────┐
│  Orbita :3210       │
│  - whatsapp-mock    │──── watches matching inboxes
│    .plugin.ts       │──── POST /api/send (outbound)
│  - InboxManager     │
└─────────────────────┘

Endpoints (miniwhatsapp side)

Method	Path	Who calls it	Purpose
POST	/api/send	Orbita plugin	Push outbound message (Orbita → a user)
GET	/api/users	Anyone	List registered users
GET	/api/messages	Browser UI	History for current thread
WS	/	Browser UI	Live inbound/outbound events
GET	/	Browser	Chat UI (public/index.html)
GET	/admin.html	Browser	Contact admin UI

Endpoints (orbita side)

Method	Path	Who calls it	Purpose
POST	/wa-webhook	miniwhatsapp server	Forward incoming browser message into agent's inbox

The Plugin (whatsapp-mock.plugin.ts)

Lives in orbita-core/plugins/ and implements the Plugin API from Stage 4b:

// Maintains a contact book: agentName → phone number
// (stored in its own MongoDB collection, NOT in core)

watch(inbox):
  if inboxMsg.toAgent has a phone number mapping:
    POST http://localhost:4000/api/send
         { to: phone, text: formatMessage(inboxMsg) }

onWebhook("/wa-webhook"):
  resolve phone → agentName via contact book
  inbox.send("whatsapp-mock", agentName, "external_message", {...})

The plugin OWNS the phone↔agent mapping. The core never sees phone numbers.

Running It

# Terminal 1 — Orbita core
cd orbita-core
npm start                    # port 3210

# Terminal 2 — MiniWhatsApp
cd ../miniwhatsapp
npm start                    # port 4000

# Browsers:
# http://localhost:4000/           — chat as any user
# http://localhost:4000/admin.html — manage contacts
# http://localhost:3210/talk       — chat with Axiom

Open multiple incognito windows to simulate multiple people.

Why admin.html exists

Initial plan was curl-driven contact management. Multi-line curl in zsh kept biting us with quoting. The admin page is a visual form for:

• Register a new user (name + phone)
• Map agent name → phone (this is the plugin's contact book)
• Simulate inbound messages (for testing without a second browser)

What this unblocks

• Full end-to-end external messaging with zero Meta dependency
• Any number of concurrent "users" (one per browser window)
• Real HTTP + WebSocket transport (no in-memory shortcuts that lie about concurrency)
• Confidence that the Plugin API genuinely handles external systems
• Real WhatsApp is now just a new plugin with the same shape

Not Implemented (by design)

• ❌ Authentication (any name/number accepted — it's a dev tool)
• ❌ Message encryption
• ❌ Media messages (text-only)
• ❌ Templates / 24h windows (those are Meta-specific)
• ❌ Delivery receipts beyond "received by server"

These belong in 5b-whatsapp (real Meta plugin).