How It Works

POST   /api/webhook/whatsapp    - Receive WhatsApp messages
GET    /api/conversations        - List conversations
GET    /api/conversations/:id    - Get conversation details
POST   /api/conversations/:id/messages - Send message
GET    /api/contacts             - List contacts
POST   /api/auth/login           - Team member login

// When message arrives
Backend receives webhook
  ↓
Stores in database
  ↓
Broadcasts via WebSocket to all connected clients
  ↓
All team members see update instantly (< 100ms)

// Webhook verification flow
1. Meta sends webhook with signature header
2. Backend computes HMAC with app secret
3. Compares computed signature with received signature
4. Only processes if signatures match
5. Prevents unauthorized webhook calls

// 1. Frontend request
POST /api/conversations/123/messages
Body: { content: "Hello! How can I help?" }
Headers: { Authorization: "Bearer <jwt>" }

// 2. Backend processing
- Validates JWT token
- Checks user has access to conversation
- Calls WhatsApp API to send message
- Stores message in database
- Broadcasts via WebSocket

// 3. WhatsApp API
- Delivers message to customer
- Sends delivery receipt webhook
- Backend updates message status

// 4. All team members see message instantly

// 1. Meta webhook
POST /api/webhook/whatsapp
Body: {
  object: "whatsapp_business_account",
  entry: [{
    changes: [{
      value: {
        messages: [{
          from: "1234567890",
          text: { body: "I need help" }
        }]
      }
    }]
  }]
}

// 2. Backend processing
- Verifies webhook signature
- Extracts message data
- Finds or creates contact
- Finds or creates conversation
- Stores message
- Broadcasts to WebSocket clients

// 3. Frontend receives
- WebSocket event triggers
- Conversation list updates
- Notification shown
- Unread count increments

┌─────────────────────────────────┐
│     Cloud Server (Railway)      │
│                                 │
│  ┌─────────┐  ┌──────────┐    │
│  │ Backend │  │ Frontend │    │
│  │ Node.js │  │ Next.js  │    │
│  └─────────┘  └──────────┘    │
└─────────────────────────────────┘
         ↓
┌─────────────────────────────────┐
│   Managed PostgreSQL Database   │
└─────────────────────────────────┘

┌────────────┐     ┌────────────┐
│  Frontend  │     │  Frontend  │
│  (Vercel)  │     │  (Vercel)  │
└────────────┘     └────────────┘
         ↓                ↓
    ┌──────────────────────────┐
    │    Load Balancer (AWS)   │
    └──────────────────────────┘
         ↓                ↓
┌────────────┐     ┌────────────┐
│  Backend   │     │  Backend   │
│  Instance  │     │  Instance  │
└────────────┘     └────────────┘
         ↓                ↓
    ┌──────────────────────────┐
    │  PostgreSQL (AWS RDS)    │
    └──────────────────────────┘