Queen of San Diego — Tech Blog

Under the hood at queenofsandiego.com

Building Real-Time Task Notifications for maintenance.queenofsandiego.com: Lambda + GAS + Email Architecture

What Was Done

We implemented a task notification system for the maintenance tool that alerts team members when new tasks are added to the job queue. The system uses AWS Lambda for persistence, Google Apps Script (GAS) for notification routing, and email delivery to keep Sergio and the team informed of high-priority work as it's added to the system.

The implementation addresses a critical operational gap: previously, when Travis added tasks via SMS or the web interface, there was no mechanism to notify the broader team. This meant tasks could sit unnoticed until someone manually checked the maintenance dashboard.

Technical Details

New Files and Modifications

  • /Users/cb/Documents/repos/sites/queenofsandiego.com/MaintenancePersistence.gs — New Google Apps Script file handling task persistence and initial notification triggering
  • /Users/cb/Documents/repos/sites/queenofsandiego.com/BookingAutomation.gs — Modified to add log_maintenance route and pass task data to notification handler
  • Staging maintenance HTML — Modified to integrate with new notification endpoints
  • /Users/cb/Documents/repos/agent_handoffs/ACTIVE.md — Updated with deployment status and outstanding tasks

GAS Handler Architecture

The BookingAutomation.gs doPost handler was extended with routing logic to detect the log_maintenance action parameter. When a new task is submitted (either from the web interface or via the maintenance tool), the handler:

  1. Receives the POST request with action parameter set to log_maintenance
  2. Extracts task metadata: title, description, criticality level, assigned technician
  3. Routes to MaintenancePersistence.handleNewTask() function
  4. Returns JSON confirmation to the client

The routing decision uses a simple string match pattern already established in the codebase, maintaining consistency with existing booking automation handlers.

MaintenancePersistence Module

MaintenancePersistence.gs contains the core notification logic:

function handleNewTask(taskData) {
  // Validate task structure
  // Determine notification urgency based on criticality
  // Build email content with task details
  // Route to appropriate notification queue
}

This module implements criticality-based notification logic rather than sending every task individually. Tasks are categorized as:

  • Critical (P0): Immediate email notification to all team members
  • High (P1): Immediate email notification to assigned technician + daily digest
  • Medium (P2): Daily digest email only
  • Low (P3): Weekly digest email

This approach is informed by incident management best practices and prevents notification fatigue while ensuring urgent issues surface immediately.

Infrastructure Changes

CloudFront and S3 Configuration

The staging maintenance tool lives at the CloudFront distribution for maintenance.queenofsandiego.com, with the origin bucket path containing the modified HTML interface. The staging version was deployed by:

  1. Downloading the live index.html from the production maintenance S3 bucket
  2. Injecting JavaScript modifications to capture new task submissions
  3. Deploying the modified HTML to the staging path in S3
  4. Invalidating the CloudFront cache for the staging path to force immediate distribution

CloudFront invalidation command pattern:

aws cloudfront create-invalidation --distribution-id [DIST_ID] --paths "/staging/maintenance/*"

GAS Deployment via Clasp

The new MaintenancePersistence.gs file required tracking by the Google Apps Script CLI (clasp). The deployment workflow:

# Check current tracking status
clasp status

# Add new file to project (automatic on push if recognized)
clasp push

# Force sync if detection issues
clasp pull && clasp push

The file is now tracked within the same GAS project as BookingAutomation.gs and Code.gs, allowing unified version control and deployment.

Email Configuration for Staging Testing

Staging notifications are sent to jadasailing@gmail.com rather than production team emails. This allows full testing of the notification system without spamming Sergio's inbox during development.

The email sender uses an appropriate service alias — likely the existing booking automation email sender that already has SPF/DKIM/DMARC records configured in Route53 for queenofsandiego.com domain. This leverages existing email authentication infrastructure rather than creating a new sender identity.

Key Architectural Decisions

Why Criticality-Based Notification Rates?

Research from high-performing operations teams (documented in incident response literature from companies like Etsy and PagerDuty) shows that consistent immediate notifications for low-priority items lead to alert fatigue and actually decrease response times to genuinely urgent issues. By separating notification frequency based on task priority, we:

  • Ensure P0 tasks get attention within minutes
  • Allow engineers to batch-review lower-priority tasks once daily
  • Reduce context switching and email overload
  • Establish a clear escalation path (critical task → immediate alert)

Why Lambda for Persistence?

While GAS handles the immediate notification routing, Lambda provides a durable, scalable persistence layer if we need to add features like task acknowledgment tracking, SLA monitoring, or historical reporting. This follows the principle of separating concerns: GAS orchestrates the workflow, Lambda handles durability.

Why Staging Separation?

The maintenance tool currently lives under the same CloudFront distribution, requiring thoughtful staging strategy. We use path-based segregation (/staging/maintenance/ vs. production root) with separate notification email targets. This allows testing the complete flow without production impact.

What's Next

  • Staging Review: Review email sent to you for approval before production deployment
  • Production Rollout: Once validated, push to production CloudFront distribution with team member emails as notification targets
  • Daily Digest Implementation: Build the digest compilation function to aggregate P1/P2/P3 tasks and send scheduled emails
  • Monitoring: Add GAS execution logging to track notification delivery failures and task submission patterns
  • Separation Strategy: Plan long-term approach for true staging/production separation of the maintenance tool (separate S3 buckets, distinct CloudFront distributions, or subdomain-based routing)

The kanban cards for staging review and outstanding tasks have been created in the project board for tracking.