Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

Building a Twilio Relay for Multi-Carrier SMS Forwarding in QuickDumpNow

What Was Done

We provisioned Twilio account credentials and designed an SMS relay system to implement cascading call forwarding for QuickDumpNow's dispatch workflow. The problem: a single incoming SMS line (the QDN main number) needed to route through Sergio's primary phone, then to his backup line (858-335-4807), with carrier-level call forwarding unable to handle the complexity. Twilio's programmable SMS and voice APIs provide the orchestration layer.

Credentials were securely stored in the shared environment file, a reference memory was created for future session continuity, and the architectural foundation was laid for a relay Lambda function that will intercept incoming messages, validate job context, and forward to the appropriate dispatcher.

Technical Details: The Relay Architecture

Credential Management & Storage

Twilio credentials were appended to /Users/cb/Documents/repos/.secrets/repos.env with file mode 600 (read/write owner only):

  • TWILIO_ACCOUNT_SID — account identifier for all API calls
  • TWILIO_AUTH_TOKEN — authentication token for admin operations (provisioning, webhook setup)
  • TWILIO_API_KEY & TWILIO_API_SECRET — SDK-preferred credentials for runtime operations

Future sessions reference /Users/cb/.claude/projects/-Users-cb-Documents-repos/memory/reference_twilio_credentials.md to locate and use these credentials without re-intake. This eliminates friction on follow-up Twilio work and maintains audit trail.

Message Flow Design

The relay will operate as follows:

  1. Customer SMS arrives at QDN Twilio-provisioned number
  2. Webhook POST to Lambda function (TBD endpoint)
  3. Lambda validates token/job context against maintenance.json (already persisted in S3)
  4. If valid, forward message body + sender to Sergio's primary phone via Twilio SDK
  5. Log forwarded message to CloudWatch; update job state if needed
  6. If Sergio doesn't respond within timeout, trigger backup-number forward

This keeps dispatcher context (job ID, vehicle, location) in Twilio logs while respecting the existing QDN state machine in lambda_function.py.

Infrastructure: Twilio & AWS Integration Points

Existing QDN Lambda Foundation

The relay will extend /Users/cb/Documents/repos/sites/dashboard.quickdumpnow.com/lambda/lambda_function.py, which already:

  • Reads/writes maintenance.json from the QDN S3 bucket
  • Manages job state transitions (pending, in-progress, completed)
  • Handles dashboard API requests and note persistence

A new handler will be added to accept POST requests from Twilio webhooks and orchestrate the forward.

API Gateway Routes

Four new routes were already provisioned on the QDN API Gateway (during the prior session) to support tracking and maintenance workflows. The Twilio relay will use a similar pattern: 

POST /relay/sms
Headers: X-Twilio-Signature (webhook auth header)
Body: {
  "From": "+1XXXXXXXXXX",
  "Body": "...",
  "MessageSid": "SM...",
  "JobId": "j_..."
}

CloudFormation or manual Route53 changes are not needed; the API Gateway already exists and CORS is handled via CloudFront function.

Monitoring & Logging

All relay activity logs to CloudWatch Logs under /aws/lambda/qdn-data-crud (or a new stack if relay becomes its own Lambda). Job state and forwarded messages are persisted to maintenance.json, providing durability and audit trail.

Key Decisions & Rationale

Why Twilio Over Native AWS Chaining

AWS Lambda + SNS could theoretically route SMS, but Twilio offers:

  • Webhook flexibility: incoming SMS can trigger custom logic before forwarding, not just blindly routing
  • Carrier compliance: Twilio handles 10DLC registration, TCPA opt-out lists, and rate limiting
  • Timeout & retry logic: built-in support for delivery confirmation and fallback routing (primary → backup)
  • Unified voice + SMS: future work (e.g., dispatcher calls vehicle directly) reuses same Twilio account

Reference Memory Over Inline Docs

Credentials and architecture decisions were documented in reference_twilio_credentials.md instead of inline code comments. This keeps secrets out of the repo, centralizes credential knowledge for multi-session projects, and allows the next engineer to onboard quickly without credential re-intake overhead.

Webhook Validation Strategy

Twilio webhooks include an X-Twilio-Signature header. The relay Lambda will validate this header (using the auth token) before processing, preventing spoofed forwarding requests. This is simpler than API key rotation and aligns with Twilio best practices.

What's Next

  • Implement relay handler: add def handle_twilio_relay(event, context) to lambda_function.py
  • Wire webhook endpoint: provision a Twilio Messaging Service and set webhook URL to the new API Gateway route
  • Test end-to-end: send SMS to QDN Twilio number, verify Lambda receives webhook, confirm forward to Sergio's phone
  • Add timeout logic: if Sergio doesn't ACK (via SMS or dashboard state change) within 5 min, forward to backup number
  • Integrate with dashboard: render forwarded messages in the job detail view so Sergio can see dispatcher notes in real time
  • Deploy & cutover: update QDN main number routing to use Twilio, monitor error logs for a week, then deprecate carrier-level forwarding

This relay is the foundation for a more sophisticated dispatch coordination system where Twilio becomes the central nervous system for QDN communication — SMS forwarding today, voice calls and SMS confirmations in the near term.

```