Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

Building a Multi-Channel Message Relay for QuickDumpNow: Twilio Integration & CloudFront Tracking

What Was Done

Over this session, we integrated Twilio SMS routing into the QuickDumpNow (QDN) platform to enable cascading customer notifications across multiple phone numbers when primary contacts are unavailable. We also deployed a customer-facing job tracking page and refactored the dashboard API to support real-time message logs. The work spans AWS Lambda, API Gateway, CloudFront distribution configuration, and a new SMS relay architecture.

The Problem We Solved

QDN's original notification flow was brittle: when a job was dispatched, messages went to one phone number. If that contact didn't answer, there was no fallback. The real-world scenario was: primary dispatcher (Sergio) → secondary (his backup at 858-335-4807) → dead end.

At the carrier level (raw SIP/PSTN), call forwarding chains are unreliable and expensive. Twilio lets us route inbound SMSes programmatically: receive on one number, inspect the job state, and forward intelligently to the next person in the chain. This became the task: implement that relay logic and surface it to customers via a tracking page.

Technical Architecture

Twilio Credentials & Account Setup

Credentials were appended to /Users/cb/Documents/repos/.secrets/repos.env with mode 600 (read-only to owner). We provisioned:

  • Account SID + Auth Token: Used for admin API calls (listing messages, provisioning phone numbers, querying account state).
  • API Key + Secret: Preferred for runtime SDK calls within Lambda functions (narrower scope, rotation-friendly).

A reference memory document was created at /Users/cb/.claude/projects/-Users-cb-Documents-repos/memory/reference_twilio_credentials.md to ensure future sessions know which credential type to use where and where to source them securely.

Lambda Function Refactoring

The main CRUD handler, /Users/cb/Documents/repos/sites/dashboard.quickdumpnow.com/lambda/lambda_function.py, was updated to:

  • Accept a new append_message operation to log SMS activity (timestamp, sender, recipient, body, status).
  • Store messages in the maintenance.json state file under each job's messages array.
  • Return message history via a new GET /api/messages/{job_id} endpoint.
  • Support Twilio webhook callbacks to record delivery status asynchronously.

Example operation call structure: 

{
  "operation": "append_message",
  "job_id": "j-12345",
  "message": {
    "timestamp": "2025-01-23T14:30:00Z",
    "from": "+12015551234",
    "to": "+18585554807",
    "body": "Job j-12345 ready for pickup",
    "status": "sent"
  }
}

API Gateway Routes

Four new routes were added to the QDN API Gateway (exact endpoint names omitted for security, but pattern-matched to /api/messages/*):

  • GET /api/messages/{job_id} — Retrieve message history for a job (customer-facing).
  • POST /api/messages — Log a new message (Twilio webhook callback).
  • POST /api/relay — Trigger cascading forward logic (internal dispatch tool).
  • OPTIONS /api/* — CORS preflight for all message endpoints.

Each route integrates with the Lambda proxy handler, which parses the operation type and delegates to the appropriate Python function.

Customer Tracking Page Deployment

A new tracking page was written to /Users/cb/Documents/repos/sites/quickdumpnow.com/track/index.html. This page:

  • Accepts a job token via query parameter (e.g., ?token=abc123def456).
  • Calls the Lambda API to validate the token and fetch job state.
  • Displays job status (queued, in-progress, completed), current location, and estimated arrival time.
  • Shows the message timeline — when QDN texted the customer, when dispatch acknowledged, etc.
  • Falls back to sample data if no token is provided (for development/demo).

The page was then deployed to the S3 bucket backing quickdumpnow.com (CloudFront distribution ID omitted for operational security). A CloudFront invalidation was issued to purge old cached versions.

CloudFront Function for URL Rewrite

A CloudFront Function was created and published to handle requests to /track. The function:

  • Inspects the request URI.
  • If the path is exactly /track (or /track/), rewrites internally to /track/index.html.
  • Preserves query parameters and fragments (so the token query param reaches the page).
  • Attaches the function to the default cache behavior of the distribution.

This avoids forcing clients to request /track/index.html explicitly and matches standard SPA routing patterns.

Message Relay State Machine

The append_message logic in the Lambda function implements a simple state machine:

  • Job creation: Job gets an empty messages array.
  • Dispatch notification: First message appended: "Job queued, dispatching to [primary]".
  • Primary acknowledged / timeout: If no response within 5 minutes, append: "No response from primary, cascading to [secondary]".
  • Customer pickup / drop-off: GPS coordinates logged; message appended: "En route to [address]".
  • Job complete: Final message: "Job completed at [time]".

Each message record includes metadata (timestamp, from/to phone, status, retry count). This enables both customer transparency and operational debugging.

Maintenance Seed Data

A baseline maintenance.json seed file was created at /tmp/maintenance_seed.json to establish the initial job state structure. This was diffed against the live version before being pushed to S3. The seed includes:

  • Job ID, customer contact, service type, location, timestamp.
  • An empty or populated messages array (depending on job age).
  • GPS waypoints (for in-progress jobs).
  • Status enum: queued | dispatched | in_progress | completed | cancelled.

This structure allows the tracking page and internal APIs