B1 & B2 Business Requirements — 10-Day Decomposition Plan Audience: Engineering team, Principal Architect, client reviewers.
Last updated: 2026-05-18
Track B1 — WhatsApp Cloud API Integration (Messaging + Calling) Owner: Backend / API Engineer (new hire)
Repository: clm-api — src/webhooks/meta/whatsapp/, new calling module, per-tenant credential storage, channel onboarding endpoints
BR-B1.1 — WhatsApp Webhook Ingestion
Receive inbound WhatsApp messages via Meta webhook
Verify webhook signature using fastify-raw-body setup
Reject tampered/invalid payloads
Route verified messages into the outbox event pipeline
BR-B1.2 — WhatsApp Outbound Messaging
Send outbound messages to customers via WhatsApp Cloud API
Per-tenant credential storage (token, phone number, display name, template list)
Credentials pre-provisioned by Meta business partner; API only stores and uses them
Circuit-breaker pattern (Cockatiel) on outbound client for resilience
Idempotency-Key support to prevent duplicate sends
BR-B1.3 — WhatsApp Calling Integration
Receive inbound call events from WhatsApp Cloud API
Initiate outbound calls via WhatsApp Cloud API
Track call state per conversation (initiated, ringing, answered, missed, ended)
Publish Call* events (CallInitiated, CallRinging, CallAnswered, CallEnded, CallMissed) through the outbox
BR-B1.4 — Calling-Event Schema
Define and publish Zod schemas in libs/contracts for all call states
Schemas consumed by tenant console (agent click-to-call) and admin console (operator monitoring)
BR-B1.5 — Channel Onboarding Endpoints
REST endpoints for both consoles to connect a tenant to WhatsApp Cloud API
Accept per-tenant credentials, write to API, surface connection state
Used by tenant console (agent side) and admin console (operator side)
BR-B1.6 — Template Message Support
Outbound template messages for outside the 24-hour customer service window
Per-tenant approved-template list served to tenant console template picker
BR-B1.7 — Production Validation
Synthetic webhook canary against staging
Call-state test matrix against production sandbox
Full end-to-end integration test: inbound webhook → outbox event → outbound message → calling lifecycle
Day-by-Day B1 Deliverables
Day
Deliverable
1
WhatsApp Cloud API integration plan (messaging + calling)
2
Webhook receiver scaffold, calling-event schemas in libs/contracts
3
Signature verification first cut, tamper-payload unit test
4
Outbound message client, per-tenant credential storage, channel onboarding REST endpoints
5
Calling integration end-to-end (API side): inbound events, outbound calls, call state, Call* outbox events
6
Cockatiel circuit-breaker on outbound client, Idempotency-Key support
7
Full sandbox end-to-end: webhook → outbox → outbound → calling lifecycle
8
Calling tool sandbox validation, synthetic webhook canary
9
WhatsApp integration docs (clm-api/docs/whatsapp.md), operations runbook
10
Production sandbox verification, call-state test matrix
Track B2 — Messaging Domain & Event Plumbing Owner: Backend / API Engineer (new hire)
Repository: clm-api — src/modules/tenant/messaging/, src/webhooks/meta/, listener migration, Pact consumer, envelope wiring, outbox consumer, messaging-service deployment
BR-B2.1 — Unified Four-Channel Message Reception
Ingest messages from Messenger, WhatsApp, Instagram, and website widget
Channel-aware MessageReceived Zod schema with channel discriminator in libs/contracts
All channels publish through the same outbox-backed pipeline
BR-B2.2 — Listener Migration (In-Process → Outbox)
Inventory all @OnEvent listeners in messaging tree (~67 files, ~167 EventEmitter2 refs)
Categorize each: "outbox-replaceable", "re-architecture needed", "stay synchronous"
Migrate replaceable listeners to outbox consumers
Every migrated listener must work identically post-extraction
BR-B2.3 — Tenant Envelope Wiring
Every queue message and outbox entry carries: tenantId, requestId, traceparent, actorId, payload
Walk every emitting site in messaging modules, confirm envelope-aware publication
CI check fails on missing tenantId
BR-B2.4 — OpenTelemetry Initialization
OTEL SDK in clm-api/src/main.ts and BullMQ worker entrypoint
traceparent propagation: Caddy → API → WorkerRaise tracesSampleRate from 0 to non-zero
BR-B2.5 — Messaging Service as Separate Process
Same clm-api image, SERVICE_MODE=messaging environment variable
Runs as its own process on the dedicated server
Behind Caddy Strangler routing flag
BR-B2.6 — Contract Testing
Consumer-side Pact for MessageReceived across all four channels
Pact verification wired into CI
BR-B2.7 — Deployment Cutover & Load Testing
Flip staging Strangler routing flag for messaging service
Load test against staging, tune connection-pool budgets per cluster-config
Verify Change Streams relay: leader-elected, no double-publishing
Production flip and verification on Day 10
Messaging-service deployment docs
Listener-inventory output
Channel-aware event contract docs
Rollback procedure
Day-by-Day B2 Deliverables
Day
Deliverable
1
API endpoint, queue, and @OnEvent listener map for messaging + Meta webhooks
2
MessageReceived Zod schema with channel discriminator, listener-inventory start
3
OTEL init in main.ts + worker entrypoint, traceparent propagation verified
4
Envelope-aware publication across all messaging emitters, begin listener migration
5
Continue listener migration, MessageReceived Pact consumer for all four channels
6
Finish listener inventory, messaging module runs as SERVICE_MODE=messaging
7
Flip staging Strangler flag, tenant cohort end-to-end in staging
8
Load tests on staging, connection-pool tuning, Change Streams relay verification
9
Deployment docs, listener-inventory output, event contract docs, rollback procedure
10
API test suite, Pact verification step, confirm production traffic on new server
Cross-Track Dependencies (B1 ↔ B2)
Dependency
Owner
Day
Breaks if missed
Calling-event schemas in libs/contracts
B1
2
B2 has no calling contract to wire
MessageReceived schema with channel discriminatorB2
2
B1 can't publish WhatsApp messages through unified pipeline
OTEL traces visible end-to-end
B2
3
Team flies blind rest of engagement
Tenant envelope CI check live
Track A
4
B1/B2 can't guarantee cross-process correctness
WhatsApp onboarding endpoints
B1
4
Both consoles can't build onboarding UI
B1 outbound client ready
B1
5
B2 Pact consumer can't verify WhatsApp channel
Messaging service runs as separate process
B2
6
Day 7 staging deployment blocked
Pact broker accepts contracts
Track A
7
Contract testing becomes optional, gets skipped
Messaging service serves staging traffic
B2
7
Day 10 production flip impossible
Summary: B1 vs B2 at a Glance
Dimension
B1 (WhatsApp)
B2 (Messaging Domain)
Focus WhatsApp Cloud API integration (messaging + calling)
Unified messaging pipeline, event plumbing, service extraction
Channels WhatsApp only
All four (Messenger, WhatsApp, Instagram, web widget)
Key schemas CallInitiated, CallRinging, CallAnswered, CallEnded, CallMissedMessageReceived (channel-aware)
Key infra Webhook receiver, outbound client, credential storage, circuit breaker
Outbox consumers, listener migration, OTEL, tenant envelope, Pact
Deployment Validates against sandbox + production
Extracts messaging service to dedicated server
Consumers Tenant console (click-to-call), admin console (monitoring)
Both consoles (agent inbox, operator surfaces)
