SignalHub — a prototype Unified Inbox (Attack Capital assignment) that aggregates SMS, WhatsApp, and extensible channels into a single threaded inbox for team-based outreach, scheduling, and analytics.
- Watch the 3–5 minute walkthrough: (Add Loom / YouTube link here)
Demo highlights: Send/Reply across channels, schedule messages, collaborate on notes, and view analytics.
- Unified messages normalized into a single
Messagemodel (SMS, WhatsApp, Email, Social). - Threaded conversations by contact (Kanban & list views).
- Composer with channel preview and scheduling.
- Twilio SMS & WhatsApp integration (inbound webhooks + outbound sending).
- Team collaboration: shared notes with
@mentionsand presence (Yjs). - Analytics dashboard (response time, channel volumes, conversion tracking).
- Role-based access (viewer / editor / admin) and trial mode handling.
flowchart LR
subgraph Frontend
F[Next.js App Router (TypeScript)] -->|API calls| API
F -->|Realtime| WS[WebSocket / Yjs Provider]
end
subgraph Backend
API[/api/* (Next.js server) / Express/Serverless endpoints/Workers/Jobs/Integrations/Prisma/Redis/Queue/Worker/]
API --> DB[Postgres (Prisma)]
API --> TW[Twilio API]
API --> EVT[Event Worker / Scheduler]
EVT --> TW
API --> YJS[Yjs Provider / Realtime]
end
DB ---|store| API
WS -->|presence & document sync| YJS
ERD (Prisma / Mermaid)
mermaid
Copy code
erDiagram
USER ||--o{ TEAM_MEMBER : ""
TEAM ||--o{ TEAM_MEMBER : ""
USER ||--o{ NOTE : ""
TEAM ||--o{ THREAD : ""
CONTACT ||--o{ THREAD : ""
THREAD ||--o{ MESSAGE : ""
THREAD ||--o{ NOTE : ""
SCHEDULED_MESSAGE ||--o{ THREAD : ""
Integration Comparison (short)
Channel Latency Approx Cost* Reliability Notes
Twilio SMS Low (100–500ms send) Low per SMS (~$0.007–$0.05) High Trial requires verified numbers; MMS supported
Twilio WhatsApp Medium Low (WhatsApp template costs apply) Medium-High Requires WhatsApp Sandbox or business approval
Email (Resend / SMTP) Medium Minimal (API costs) High Rich content; deliverability considerations
Twitter/X DMs Depends on API quota Varies Medium OAuth setup needed
*costs are illustrative — check provider docs for latest pricing.
Getting Started (local dev)
Prereqs
Node.js >= 20, pnpm/npm/yarn
Docker (for local Postgres) or a managed Postgres (Supabase)
Twilio account (trial support for SMS & WhatsApp sandbox)
(Optional) Resend API key for email testing
Quick start (development)
bash
Copy code
# 1. clone
git clone https://github.com/<you>/signalhub.git
cd signalhub
# 2. copy env
cp .env.example .env
# 3. start Postgres locally (recommended Docker Compose)
docker compose up -d
# 4. install
pnpm install
# 5. prisma migrate & seed (if provided)
pnpm prisma migrate dev --name init
pnpm prisma db seed
# 6. run dev
pnpm dev
Environment variables (.env.example)
ini
Copy code
# App
NEXT_PUBLIC_APP_NAME=SignalHub
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=change_this_secret
# Database
DATABASE_URL=postgresql://postgres:password@localhost:5432/signalhub
# Twilio
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_PHONE_NUMBER=+1XXXXXXXXXX
TWILIO_WHATSAPP_SANDBOX=whatsapp:+14155238886
# Resend (optional)
RESEND_API_KEY=live_xxx
# JWT / session secret
JWT_SECRET=super_secret_change_me
# Encryption key for private notes (symmetric)
NOTES_ENCRYPTION_KEY=32_byte_base64_or_hex_key
API Highlights
POST /api/webhooks/twilio — inbound Twilio webhook (with Twilio signature validation)
POST /api/messages/send — send message (payload validated by Zod; uses lib/integrations to pick sender)
GET /api/contacts/:id/thread — get full thread + notes
POST /api/schedule — schedule a future send (stores job in ScheduledMessage)
GET /api/analytics — aggregated metrics for dashboard
Implementation notes & design decisions (talking points)
Unified message model: single Message table with channel enum + metadata JSON. Allows unified UI while keeping provider specifics in metadata.
Integration factory: lib/integrations.ts exposes createSender(channel) so adding new channels is plug-and-play.
Real-time collaboration: Yjs for CRDT + presence for inline notes and @mentions. This avoids locking conflicts.
Scheduling: simple DB-driven schedule table and a worker that polls due records (easy to implement and demonstrable). For production use switch to bullmq + Redis.
Security: validate Twilio webhooks using their signature; store secrets in env and restrict private notes encryption keys to server.
Optimistic UI: React Query for instant UX when sending and updating messages; roll back on error.
Dev & Deploy tips
Use pnpm for consistent installs.
pnpm build -> pnpm start for production.
For deploy consider Vercel (frontend) + Render / Railway / Supabase (Postgres + Backend/Workers). Keep background worker as separate process (e.g., node worker.js).
How to demo (script / talking points)
Show login (Google + credentials) and roles (viewer/editor).
Open the Unified Inbox → demonstrate thread grouping & channel badges.
Click a contact modal → show history timeline & private/public notes. Use @mention and show real-time sync with another browser tab.
Compose & send an SMS → show message appears instantly (optimistic update) and webhook arrival in DB.
Schedule a follow-up → show it in the scheduled list; show worker sending it (or fast-forward in logs).
Open Analytics → point out response time & channel volume charts.
Point to code: highlight lib/integrations.ts, api/webhooks/twilio, and Prisma schema.
What I completed for this repo (for reviewers)
Twilio SMS & WhatsApp integration (send + inbound webhook)
Threaded inbox UI & composer with optimistic updates
Contact modal with history & notes (Yjs skeleton integrated)
Basic scheduling layer (DB + worker)
Analytics calculation endpoints & frontend charts
Full README (this file), ERD diagram (Mermaid), and demo script
Roadmap / Next steps
Add Email inbound (Gmail push) & outbound (Resend).
Add full Twilio Voice integration for in-browser calls.
Add Redis + bullmq for robust job processing + retries.
Add fuzzy dedupe via pg_trgm and contact merge UI.
Harden RBAC and add audit logs for compliance.
Contributing
Branch from main → open PR. Follow commit message format and ESLint/Prettier checks. Add unit tests for integration adapters.
License
MIT © Your Name
Contacts
Project lead: Sankha Subhra Das — sankhasubhradas1@gmail.com
Repo: https://github.com/<you>/signalhub
yaml
Copy code
---
If you want I can:
- Convert this README into a polished **README.md file in your repo** (I can prepare a file content only — paste it where you want), or
- Generate the Prisma schema + `lib/integrations.ts` skeleton and `/api/webhooks/twilio` handler next (I can produce working code snippets).
Which would you like next?