Skip to content

MAN-TEC-001: Communications Hub Integration

This manual defines the patterns for consuming the Sovereign Communications Hub to orchestrate community engagement across multiple channels.

1. Core Architecture

All communication is routed through the CommunicationsHub singleton. This hub utilizes a Swappable Provider architecture, ensuring environment safety via an automated sandbox (Trap).

import { CommunicationsHub } from "@sd/foundation-communications";

2. Capability Matrix

Feature Provider Shorthand Use Case
Google Meet Workspace CommunicationsHub.workspace Scheduled community meetings, mediation.
WhatsApp Twilio CommunicationsHub.whatsapp Async community outreach, resident alerts.
PTT LiveKit CommunicationsHub.ptt Real-time security/maintenance voice chat.
Chat Space Workspace CommunicationsHub.chat Internal system alerts and space monitoring.
Physical Mail Lob CommunicationsHub.mail Legally-binding notices (Delinquency, Fines).

3. Implementation Patterns

3.1 Google Meet Orchestration

To create a meeting link for a specific event:

const meetLink = await CommunicationsHub.workspace.createMeetLink(
  "Mediation: Unit 402",
  new Date("2026-03-01T10:00:00Z")
);

3.2 Community WhatsApp

Send transactional messages or alerts:

await CommunicationsHub.whatsapp.sendWhatsApp(
  "+521234567890",
  "Your maintenance request #123 has been completed."
);

3.3 Real-Time PTT Token (LiveKit)

Generate tokens for the client-side UI to join a voice channel:

const token = await CommunicationsHub.ptt.generateToken(
  "security_channel_1",
  "user_id_001",
  "Gatehouse Officer"
);

4. Environment Safety (The Trap)

In non-production environments, the CommunicationSandbox automatically intercepts all signals.

  • Behavior: Instead of sending real emails or WhatsApps, the hub logs a [Sandbox] TRAPPED message to the console.
  • Verification: Use diagnostic scripts to verify that signals are being generated correctly without burning real credits.
# Verify all channels locally
npx tsx scripts/diagnostics/verify_communications.ts

5. Metadata Mapping

Use @cap tags when implementing new communication flows to maintain the Sovereign Architecture Graph:

  • @cap COM-HUB-ROUTER: General hub usage.
  • @cap COM-HUB-GWORKSPACE: Google Workspace orchestration.
  • @cap COM-HUB-TWILIO: WhatsApp/SMS usage.