cm_whatsapp_bot_v1/docs/superpowers/specs/2026-05-09-web-app-design.md

Web App Design — Telegram-Free Pivot

Status: Draft Date: 2026-05-09 Supersedes: Sections of 2026-05-03-whatsapp-bot-design.md that describe Telegram as the primary control surface.

1. Why this exists

After live-testing the Telegram bot we hit limits that don't go away with more menu polish:

• Markdown parsing is fragile; user content breaks rendering.
• callback_data is capped at 64 bytes; complex flows need stateful workarounds.
• No native date/time picker; we rebuilt a year/month/day grid by hand.
• Media UX (uploading photos, previewing video) is awkward in chat.
• Keyboard navigation through deep menus is slow for daily use.

The operator wants to install the controls as a Progressive Web App on his phone so they look and feel native. This document describes the migration: the Telegram bot is removed entirely and replaced by a Next.js PWA.

2. Stakeholders & access

• Operator (brother): sole end-user. Uses the PWA daily.
• Developer (you): builds, deploys, occasionally debugs.
• No login. The web app is reachable only at https://wabot.04080616.xyz. Whoever resolves that hostname and reaches port 443 has full control. Single seeded operators row in Postgres represents the brother for audit purposes; the app does not authenticate the request — it trusts the network perimeter (aaPanel reverse proxy + HTTPS).

This is an explicit trade-off. Risk: a leaked URL = full access. Mitigation: rotate by changing the subdomain. Defense in depth via rate limiting + strict referer checks below.

3. Tech stack

• Next.js 16 (App Router), TypeScript end-to-end.
• Tailwind CSS v4 + shadcn/ui components (latest registry).
• Geist font via next/font.
• react-hook-form + zod for forms (same zod schemas validated client-side and re-validated in server actions).
• @serwist/next for PWA service worker.
• Drizzle ORM (already in packages/db).
• pg for LISTEN in the SSE endpoint.

No new database tables; all reads/writes hit the existing schema from 2026-05-03-whatsapp-bot-design.md §9.

4. Service topology

┌─────────────────────────────────────────────────────┐
│              Home Docker server                     │
│                                                     │
│  ┌──────────────┐         ┌──────────────┐          │
│  │     web      │         │     bot      │          │
│  │  Next.js 16  │◄───────►│   Node.js    │          │
│  │  PWA + UI    │   via   │   Baileys    │          │
│  │  Server      │ Postgres│   pg-boss    │          │
│  │  Components  │ (LISTEN/│   sender     │          │
│  │  + Server    │  NOTIFY)│   ipc        │          │
│  │  Actions     │         │              │          │
│  └──────┬───────┘         └──────┬───────┘          │
│         │                        │                  │
│         │   shared volume:       │   /data/sessions │
│         │   /data/media          │                  │
│         │                        │                  │
│         └────────────┬───────────┘                  │
│                      │                              │
│                      ▼                              │
│         aaPanel reverse proxy ─► wabot.04080616.xyz │
└─────────────────────────────────────────────────────┘
                      │
                      ▼
              Postgres at 192.168.0.210

Container responsibilities (post-pivot)

Container	Role
web	All UI (Server Components for reads; Server Actions for mutations); SSE endpoint for live events; PWA service worker; QR PNG rendering for pair flow.
bot	Baileys WhatsApp sessions; pg-boss scheduler; fire-reminder; sender; group sync; IPC consumer that listens to bot.command Postgres notifications and dispatches to the right module. No more Telegram code.

Web ↔ bot channel

Same as before — Postgres LISTEN/NOTIFY. Web writes a row + pgNotify('bot.command', ...); bot consumes; bot writes results back + pgNotify('web.event', ...); web's SSE endpoint relays to the open browser.

5. Access stance (no auth)

• No login screen, no session cookies, no CSRF tokens (server actions handle their own).
• aaPanel is the only ingress. Bot's :8081 health port is unreachable from outside.
• Rate limit at Next.js middleware: 30 requests / 10 sec per source IP. Anything more = 429.
• Origin/Referer check on Server Actions: Next.js 16 enforces this by default for actions; we leave it on.
• Rotate the subdomain if the URL ever leaks.
• Audit log is still written for every action, with operator_id set to the single seeded operator row.

6. Routes

/                              Dashboard (overview cards)
/accounts                      Accounts list
/accounts/new                  Pair new account (live QR)
/accounts/[id]                 Account detail
/accounts/[id]/groups          Groups list (paginated/searchable)
/accounts/[id]/pairing         Live pair flow page (QR + status)
/groups/[id]                   Group detail + send test
/reminders                     Reminders list
/reminders/new                 Reminder wizard (?step=1..5)
/reminders/[id]                Reminder detail (history, edit, delete)
/settings                      Profile (display name, default timezone)

# Server-side only — no public REST API for mutations:
GET /api/events                Single SSE stream (read-only, public-safe)

All other /api/* paths return 404 (configured at aaPanel and as middleware match-all).

Why no REST API for mutations

• Server Actions in Next.js 16 are first-class. They post to the page's own URL with an encrypted action ID, run on the server, return a serializable result, and integrate with revalidatePath / revalidateTag automatically.
• The browser never sees /api/reminders etc. as discoverable URLs.
• Type-safe end-to-end: the server action's return type flows through to the calling component without manual fetch boilerplate.

7. Live updates (SSE)

GET /api/events streams Server-Sent Events. The handler:

1. Connects to Postgres with a dedicated client (LISTEN web.event).
2. Forwards each notification's payload to the client as an SSE message:

event: session.qr
data: {"accountId":"...", "qrPng":"<base64>"}

event: session.connected
data: {"accountId":"...", "phoneNumber":"+60..."}

event: groups.synced
data: {"accountId":"...", "count":12}

event: reminder.fired
data: {"reminderId":"...", "runId":"...", "status":"success"}

event: reminder.failed
data: {"reminderId":"...", "error":"..."}

event: session.disconnected
data: {"accountId":"..."}

3. On disconnect, releases the PG client.

Client side: a single useEvents() hook opens the stream once at app mount. Each event triggers queryClient.invalidateQueries for the relevant key — the React Query cache stays fresh without polling.

8. Pair flow (replaces Telegram QR delivery)

Operator on /accounts → tap "Pair New Account" → /accounts/new
  Form: { label: string }
  Submit → server action: pairAccountAction(label)
                ├─ Insert whatsapp_accounts row { status:'pending', label }
                └─ pgNotify('bot.command', { type:'account.start_pairing', accountId })
  Server action returns { accountId } and the page redirects to /accounts/[id]/pairing

/accounts/[id]/pairing (server component renders shell + client island for SSE)
  Shows label, account ID, "Waiting for QR…" shimmer
  Client component subscribes to SSE
                ↓
  Bot's IPC consumer picks up notification:
    sessionManager.start(accountId)
    Listens for Baileys events:
      qr     → render PNG (base64) → pgNotify('web.event', { type:'session.qr', qrPng })
      open   → update DB + sync groups → pgNotify('session.connected') + 'groups.synced'
      close (loggedOut) → pgNotify('session.timeout')
                ↓
  Browser:
    On 'session.qr' — replace shimmer with <img src="data:image/png;base64,..."> + 30s countdown ring
    On 'session.connected' — show ✅ Connected as +60xxx + auto-redirect to /accounts/[id] after 3s
    On 'session.timeout' or 5-min server timer — show "Pairing timed out" + "Try again" button

The 5-min server-side timeout from plan 2 stays (in bot). On timeout the bot deletes the pending row and pgNotifies session.timeout.

9. Reminder wizard (replaces Telegram menu)

/reminders/new is one page that uses URL search params for state (?step=N&...). Five steps, each rendered server-side, with a server action per step that validates and redirects to the next step's URL.

Step	Inputs	Notes
1 — Account	radio list of paired accounts	shown as cards: label, phone, last connected status
2 — Groups	checkbox list with search	multi-target — gain over plan 2's single-group constraint
3 — Compose	textarea + file upload	drag-drop on desktop, native picker on mobile; file uploads go to /data/media via server action uploadMediaAction
4 — When	<input type="datetime-local"> + quick-pick chips	native iOS/Android datetime picker; chips for Now / Tomorrow 9 AM / Next Mon 9 AM
5 — Review	rendered summary + [Schedule]	server action createReminderAction writes DB + schedules pg-boss job

Edit-on-the-fly: each step has a "← Edit account / groups / body / time" link that navigates back to that step with the data preserved in URL.

URL-state is sufficient for v1 — small enough to fit in a query string. If we ever need to support multi-MB body content (drafts), we move to a reminder_drafts table.

10. Visual & layout

• Mobile-first. Tailwind breakpoints: sm: and up = "desktop layout"; below = single-column with comfortable tap targets (≥44px).
• shadcn/ui components throughout. Latest registry: Sidebar, Dialog, Form, DataTable, Sonner (toast), Sheet (mobile drawer), Tabs, Skeleton, Card.
• Light + dark mode auto-follows system; manual toggle in /settings.
• Spacing rhythm: 4 / 8 / 16 / 24 / 32 px.
• Typography: Geist (default).
• Status colors: green (connected/success), amber (pending/disconnected), red (banned/failed), neutral (ended).
• Production-grade visual layer is delegated to the frontend-design:frontend-design skill during implementation — it handles spacing, hierarchy, and feel.

Layout shape

Viewport	Shell
Mobile (<640px)	Top app bar (title + back) + bottom nav (Dashboard / Accounts / Reminders / Settings). Sheets for filters, dialogs for confirms.
Desktop (≥640px)	Left sidebar (collapsible) with same nav items + secondary nav for "New Account" / "New Reminder". Main content area with breadcrumbs at top.

11. PWA

• app/manifest.webmanifest — name, short name, theme color, 192px + 512px icons, display: standalone, start_url: /, background_color.
• Service worker via @serwist/next (Workbox successor designed for App Router):
  • Cache app shell (HTML for navigation routes, CSS, JS, fonts) — instant launch after first visit.
  • Network-first for data routes (so live data still wins).
  • Static assets cache-first.
  • Offline fallback page rendered if no network.
• iOS install via apple-mobile-web-app-capable + apple-touch-icon meta tags.
• "Install on home screen" prompt rendered on the dashboard if beforeinstallprompt fires.

12. Telegram removal (must happen first in implementation)

The plan-3 implementation starts with deleting Telegram-related code so the bot container builds clean afterward.

Files / modules deleted

• apps/bot/src/telegram/ — entire directory (bot.ts, callbacks.ts, menus.ts, state.ts, commands/, middleware/)
• apps/bot/src/media/ingest.ts Telegram-side download (replaced by web upload action)
• Telegram-specific tests in apps/bot/src/telegram/**/*.test.ts

Files modified

• apps/bot/src/index.ts: drop createTelegramBot / tg.start / shutdown.tg.stop. Replace with startCommandConsumer(boss) from a new apps/bot/src/ipc/command-consumer.ts.
• apps/bot/package.json: remove grammy, keep qrcode (still needed for QR PNG rendering, but moves usage — see below).
• apps/bot/src/whatsapp/qr-renderer.ts stays (called from the new IPC consumer's pair-handler).

New modules

• apps/bot/src/ipc/command-consumer.ts — subscribes to Postgres LISTEN bot.command, dispatches:
  • account.start_pairing → starts Baileys session, wires QR/open/close events to pgNotify('web.event', …)
  • account.unpair → existing unpair logic
  • account.sync_groups → group sync
  • group.send_test → existing send-test
• apps/bot/src/ipc/notify.ts — typed pgNotify(event, payload) helper.

Env keys removed

• TELEGRAM_BOT_TOKEN
• TELEGRAM_OPERATOR_WHITELIST
• TELEGRAM_QR_CHAT_ID

SEED_OPERATOR_TELEGRAM_ID still exists for backwards-compat with the seed script but the value loses its meaning; we keep the seeded operators row for audit log foreign keys.

Cleanup tests

• All vitest tests under apps/bot/src/telegram/ deleted along with the source.
• New tests: IPC consumer dispatch tests (mocked PG client), web's pair-flow server action tests (against a real test DB).

13. Error handling

Failure	Detection	Response
WA send transient	sender throws	pg-boss retries 3× with backoff (already in plan 2). On final failure, reminder_run_targets row gets status='failed'. SSE pushes reminder.failed → toast in UI.
WA session lost	Baileys close event	account row → disconnected. SSE pushes session.disconnected → status badge in /accounts goes amber. Auto-reconnect after 5 sec.
Pair timeout	bot's 5-min timer	Account row deleted. SSE pushes session.timeout → page navigates to "try again" view.
Server action validation	zod parse fails	Returns { ok:false, errors: { field: msg } }. Form re-renders with field-level errors.
Postgres unavailable	drizzle throws	Both containers log error, restart via Docker. UI shows a banner "Reconnecting…" if the SSE channel drops.
Media upload exceeds limit (50MB)	server action rejects	Returns error; UI shows "File too large".
SSE channel drops	EventSource fires error	Client reconnects with exponential backoff (built into EventSource).

14. Observability

• Logs: pino JSON to stdout, captured by Docker (unchanged).
• Health endpoints:
  • Web: GET /api/health — DB ping + commit SHA + uptime.
  • Bot: internal :8081/health — DB ping + per-WA-session counts.
• Per-reminder audit trail stays in DB.
• Sentry hookup deferred (out of scope for this design).

15. Build, deploy, and dev experience

• New Dockerfile: docker/web.Dockerfile (currently a placeholder). Multi-stage: deps → build (pnpm --filter @cmbot/web build → .next/standalone) → runtime (node apps/web/.next/standalone/server.js).
• New service in compose: web (replaces the existing placeholder).
• apps/web/ package: @cmbot/web, depends on @cmbot/db and @cmbot/shared workspaces.
• aaPanel reverse proxy: existing config block updated to forward to web:3000 and pass through SSE headers; deny /api/* except /api/events.

Local dev:

• scripts/dev.sh up brings web alongside tools + bot.
• Hot reload: web mounts apps/web/src (and dependent packages) into the container; next dev watches.

16. Out of scope (for this plan)

• Recurring reminders (RRULE) — same plan-2 deferral; web wizard supports one-off only for now.
• Standalone media library page — media is attached to reminders, not browseable separately yet.
• E2E browser tests (Playwright) — manual test runbook in plan 3 covers verification.
• Sentry / external error tracking.
• WebPush notifications (the operator already gets WhatsApp messages on his phone; PWA badging is enough).
• Multi-operator (still single-tenant).
• Passkeys / WebAuthn (only relevant if we add auth later).

17. Confirmed values

Inherits from the master spec:

• Subdomain: wabot.04080616.xyz
• Default timezone: Asia/Kuala_Lumpur
• Postgres: 192.168.0.210 / wabot
• Media retention: 90 days

New for this design:

• Component library: shadcn/ui
• Visual style: clean utility / admin dashboard
• Auth: none (URL is the secret)
• Real-time: SSE
• Service worker: @serwist/next