System Architecture: HLD & LLD

Customer sends "How much do your cakes cost?"
  │
  ├─ 1. Webhook/Widget receives message
  │     └─ Verify signature (WhatsApp HMAC / widget token)
  │     └─ ACK 200 immediately (< 100ms)
  │
  ├─ 2. Resolve or create contact
  │     └─ POST /contacts { external_id, channel, display_name }
  │     └─ Contact Intelligence returns contact_id
  │
  ├─ 3. Fetch contact context (parallel)
  │     └─ GET /context/{contact_id}?query="How much do cakes cost"
  │     └─ Returns: mood, memories, entities, context_text, adaptation hints
  │     └─ Target: < 30ms
  │
  ├─ 4. Call AI Brain for response
  │     └─ POST /brain/chat { message, context_text, personality }
  │     └─ Brain handles: routing → specialist → tools → RAG → streaming
  │     └─ Returns: SSE stream of tokens
  │
  ├─ 5. Deliver response to customer
  │     └─ Widget: stream SSE tokens directly
  │     └─ WhatsApp/Telegram: buffer full response, send via API
  │
  ├─ 6. Ingest interaction into Contact Intelligence
  │     └─ POST /ingest { contact_id, message, role: "user" }
  │     └─ POST /ingest { contact_id, message, role: "assistant" }
  │     └─ CI handles: mood classification, memory extraction, entity extraction
  │     └─ Returns 202 (async processing)
  │
  └─ 7. Persist to DB + broadcast to dashboard
        └─ INSERT into chat_messages
        └─ WebSocket/SSE event to Unified Inbox

interface ChatSession {
  id: string
  tenantId: string
  contactId: string          // → Contact Intelligence contact
  channelId: string          // → ChannelIntegration
  status: "ai_handled" | "human_escalated" | "closed"
  assignedAgentId?: string
  summary?: string           // AI-generated on close
  slaBreachAt?: Date
  messageCount: number
  createdAt: Date
  lastMessageAt: Date
}

POST /webhooks/whatsapp/{tenantId}
  ├─ Verify HMAC-SHA256 signature (< 1ms)
  ├─ Parse webhook payload → normalize to internal format
  ├─ Dedup check: external_message_id unique constraint
  ├─ Find or create ChatSession
  ├─ Resolve ContactIntelligence contact
  ├─ Run orchestration pipeline (steps 2-7 above)
  └─ Return 200 OK

POST /chat/widget/message
  ├─ Validate widget token against ChannelIntegration
  ├─ CORS check: origin must match registered domain
  ├─ Run orchestration pipeline
  ├─ Stream AI Brain response as SSE events
  │     event: token → { text: "Our" }
  │     event: token → { text: " cakes" }
  │     event: done  → { session_id, message_id }
  └─ Return SSE stream

AI Brain returns [[HANDOFF]] in response
  ├─ Chat Engine intercepts (does NOT send to customer)
  ├─ Send fallback message: "Connecting you to a team member..."
  ├─ Update session: status = "human_escalated"
  ├─ Set sla_breach_at = NOW() + 15 minutes
  ├─ Fire WebSocket event: chat:escalated
  └─ Agent sees it in Unified Inbox

# Chat Engine wrangler.toml
[[services]]
binding = "BRAIN_SERVICE"
service = "logicspike-brain-service"
 
[[services]]
binding = "CI_SERVICE"
service = "logicspike-contact-intelligence"
 
[[services]]
binding = "COMMS_SERVICE"
service = "logicspike-communication"