#110 Design: Inbox UI for v1.1

[Anonymous]

Originally created by: Waqasahmedwaseer

Architecture phase for the v1.1 flagship — Inbox. Design only, no code. Per the CLAUDE.md workflow: design doc → maintainer approval → implementation.

📄 Full design: docs/designs/inbox.md (github.com)

Summary

Turns WaSphere from a send-only API into a two-way platform. Today nothing in the dashboard persists inbound messages (wa-server just fires message.received). The Inbox adds:

• Greenfield data model — Contact / Conversation / Message (+ enums, indexes). All net-new tables → single additive migration, zero backfill, zero risk to existing data.
• Ingestion hooked into the existing POST /internal/webhook-event/:workspaceId → persists messages idempotently.
• REST + SSE — cursor-paginated list/thread/send endpoints + a Server-Sent-Events stream for realtime (no WebSocket, no Redis — fits the single-instance, self-hosted model).
• ShadCN-only UI — two-pane list/thread/composer built strictly from the existing design system (Dialog/Sheet/Card/Avatar…). No bespoke CSS, no hand-rolled overlays, no z-index hacks → light/dark + mobile work for free.
• #54 poll-vote integration — lands in parallel; degrades gracefully if it slips.
• 6 independently-mergeable commits; main never broken; real-Postgres + real-test-number testing (no mocks).

Scope

In: persist in/out messages, 1:1 conversations, list/thread/composer (text + 1 image + saved replies), search/filter/unread, delivery status, SSE realtime.
Out (→ v1.2+): groups, multi-agent assignment, internal notes, AI replies, multi-instance scaling, edit/delete.

⚠️ Top open questions for maintainer (need decisions before impl)

1. Multi-session per contact — one thread per (session, contact) [recommended] vs merge across numbers?
2. Groups — confirm out of v1.1 (1:1 only)?
3. Composer media — text + single image only for v1.1 [recommended]?
4. Message retention — keep forever vs configurable window (e.g. 90 days)?
5. Notifications — browser/desktop in v1.1, or visual-only (badge/sound)?

(Full list of 8 in §12 of the doc.)

---

🤖 Generated with Claude Code

[Anonymous]

Originally posted by: Waqasahmedwaseer

Revised per maintainer review (2026-06-04) — now ready for review.

All 5 decisions + 5 hardening additions applied:

• ✅ Q1 one-per-(session,contact) + future Customer view (v1.5) · ✅ Q2 groups → v1.2 · 🟡 Q3 composer = text + image + document · ✅ Q4 keep-forever (retentionDays → v1.2) · ✅ Q5 visual notifications only
• A outbound capture forward-only · B session-delete → read-only archive (sessionDeletedAt) · C whatsappName/savedName resolution · D SSE limits (10/ws, 3/user, idle+sweep) · E composer offline disabled state (durable send-queue → v1.2)

One new low-stakes question (§12): new-message sound — per-user toggle vs global mute (safe default proposed). Otherwise ready to start Commit 1 (data model + migration) on approval.