Phone & SMS Stack - irl.coop

Architecture: Centralized Gateway

Instead of separate PBX instances per group, we use a central irl.coop telephony gateway that handles all DIDs (Direct Inward Dialing numbers) and routes traffic based on the "Called Number" (DNIS).

Flow: Carrier (DID) -> irl.coop Gateway -> Group Logic -> Member/Service

1. DID Provisioning (The Numbers)

We need an API-driven provider to buy/release numbers on the fly when groups are created.

• Requirements:
  • Instant provisioning API.
  • SMS enabled (critical for Venmo 2FA).
  • SIP Trunking for voice.
• Candidates:
  • Telnyx: robust API, good pricing, detailed SMS handling.
  • SignalWire: Low latency, developed by FreeSWITCH creators.
  • Twilio: Industry standard, but more expensive.
  • Bandwidth: Wholesale focus.

2. The Gateway (The Brain)

A software switch that receives the call/text and decides where it goes.

• Technology: FreeSWITCH.
  • Decision: Chosen for API hooks (ESL), multi-tenant routing power, and scalability.

3. Routing Logic

SMS Routing (Venmo & Chat)

Orchestration: Temporal.io handles the state and workflow. When an SMS arrives:

1. Ingest: Gateway pushes event to Temporal workflow.
2. Display: Content appears in Group Chat as an Alert/Notification.
3. Action:
   • Puppeteer (controlled by Temporal) waits for specific patterns (e.g., "123456 is your code").
   • Security: Instead of silent auto-capture, maybe requires human confirmation or is visible to admins? (User choice: auto-parse vs human-assist).

Voice Routing

When a call arrives:

1. IVR / Auto-Attendant: "Thanks for calling Swim Buddies..."
2. Extensions: "Press 1 for Joe, 2 for General Info".
   • Lookup: Map extension to Member's real phone (masking) or their WebRTC client (browser call).
3. Availability: Check Member's status.
   • Online: Ring them.
   • Busy/Offline: Send to Group Voicemail (transcribed to Chat).

4. Integration

• Puppeteer Bot: Needs a websocket or webhook listener to receive 2FA codes instantly from the Gateway.
• Web Dashboard: Members configure their extensions and availability here.