ms-communication — Chats, Calls & Notifications

Real-time messaging and voice. A Nodevel service on MongoDB, with Firestore as the live message store.

• Stack: Express/Nodevel, Mongoose/MongoDB, Socket.IO (+ Redis adapter), Firebase/Firestore.
• Port: 8080.

Responsibilities

• Messaging — text chat over Socket.IO + Firestore; Slack thread sync; message persistence.
• Voice/video calls — Twilio and Telnyx PSTN ↔ ElevenLabs media-stream bridges, WebRTC (LiveKit) token relay for widget AI calls, recording links, inbound/outbound automation, post-call webhooks. See Telephony.
• Notifications — APN (iOS VoIP push), FCM (Android), email (SendGrid/ nodemailer).
• Multi-tenant routing — associate users/teams/rooms with companies.
• Webhooks — Twilio call events; Slack event subscriptions.

Boot flow

Standard Nodevel (index.js → Application.run() → app/hooks.js). boot() loads Redis, Auth, Mongo, Cron, Logger, Mail, Permissions, Firebase, Firestore, Slack, APN, FCM, and an ElevenLabs voice bridge.

Directory map

app/
├── models/       chats, inbound_outbound_calls, user_devices, companies, agencies
├── services/     ApnService, FcmService, FirestoreService, MailService, SlackService,
│                 MessagingService, SocketService, ElevenLabsBridgeService,
│                 PostCallWebhookService, RecordingLinkService
├── controllers/  MessageController (large — chat logic), CallsController,
│                 InboundCallController, OutboundCallController,
│                 InboundOutboundCallController, TelnyxInboundCallController,
│                 TelnyxOutboundCallController, SlackController
├── helpers/      TelnyxHelper (TeXML), AudioTranscodeHelper (mu-law + A-law), …
├── jobs/         cron jobs (e.g. recording merge)
├── keys/         APN cert (.p8), Firebase service account
└── routes/       api.js  (Telnyx routes are declared in the controllers' routes())

Data models

Model	Purpose
chats	thread metadata with embedded messages[] (sender, text, status, timestamp, slack_thread_id)
inbound_outbound_calls	call_sid, status, duration, recording_url, company_id, provider (twilio/telnyx), sentiment, voicemail, call_outcome, post_call_webhook_sent_at
user_devices	push tokens (apn_token, fcm_token, os)
companies / agencies	tenant + Twilio/Slack config

Endpoints & socket events

• HTTP: health, POST /auth/login, POST /webhooks/twilio/inbound, Slack OAuth callback + POST /integrations/slack/events (raw-body signature verification).
• Telephony: POST /twilio/{inbound,outbound}-voice/:company_id, POST /twilio/inbound-dial-fallback/:company_id (routing-priority chain), POST /telnyx/{inbound,outbound}-voice/:company_id + -status callbacks, POST /telnyx/preheat-outbound/:company_id/:agent_id, POST /inbound-outbound-calls/save (post-call persistence). Media-stream WS upgrades on /twilio/media-stream and /telnyx/media-stream (path selects the carrier/codec path in ElevenLabsBridgeService).
• Socket.IO: message:send → message:received (room broadcast), call:initiate → Twilio bridge, notification:push → APN/FCM. A Firestore listener on /rooms/{room_id}/messages keeps clients in sync.

Integrations

Twilio (calls/recording), Telnyx (TeXML second carrier), APN (iOS VoIP push), Firebase Admin (FCM + Firestore), SendGrid/nodemailer (email), Slack Web API, ElevenLabs (Convai voice — websocket bridge + WebRTC/LiveKit tokens), AWS S3 (call recordings).

Realtime

Socket.IO 4.8 with @socket.io/redis-adapter for multi-pod fan-out; SocketService mirrors message state between Socket.IO and Firestore.

Cross-service

Receives auth/tenant config from backend; pushes call-completion and read receipts back via webhook; queries ms-sessions presence to confirm a participant is live. See Cross-Service Communication.

Deployment

Docker (Node 22 Alpine, port 8080) → ECR → EKS. HTTP pods scale on CPU; no separate worker pool (jobs are cron-based; the exactly-once post-call webhook fallback deliberately lives in the single-pod backend, not here). buildspec.yml builds, pushes, and rolls out. Secrets (TWILIO_*, SLACK_*, FIREBASE_KEY, TELNYX_MEDIA_STREAM_PATH, TELNYX_PUBLIC_WS_URL, RECORDING_LINK_SECRET) come from the cluster.