Queen of San Diego — Tech Blog

Under the hood at queenofsandiego.com

Building Real-Time Task Notifications for maintenance.queenofsandiego.com: Architecture, Infrastructure, and Notification Strategy

What Was Done

We implemented a comprehensive task notification system for the maintenance management tool at maintenance.queenofsandiego.com. This system captures newly-added maintenance tasks, evaluates their criticality, and routes notifications to team members (Sergio and CB) via email with intelligent batching logic. The solution spans multiple infrastructure layers: Google Apps Script (GAS) for task persistence and notification handling, a Lambda function for managed email delivery, and client-side HTML modifications for task visibility.

The implementation follows industry best practices for notification frequency based on task priority: critical tasks trigger immediate notifications, while routine tasks are batched into daily digests. This prevents notification fatigue while ensuring urgent issues receive immediate attention.

Technical Architecture Overview

The notification pipeline consists of four primary components:

  • Client Layer: Modified staging HTML at /Users/cb/Documents/repos/sites/queenofsandiego.com/tools/maintenance/staging-index.html captures task creation events
  • Persistence Layer: New GAS file MaintenancePersistence.gs stores task metadata and notification state
  • Routing Layer: Updated BookingAutomation.gs doPost handler routes log_maintenance actions to appropriate handlers
  • Delivery Layer: Lambda function (referenced as tips-box pattern in existing deployments) sends templated emails via SNS

Infrastructure Details

S3 & CloudFront Configuration

The staging maintenance tool is deployed to S3 with CloudFront distribution. Key resources:

  • S3 Bucket: Primary maintenance assets stored in the queenofsandiego.com S3 bucket
  • CloudFront Distribution: Fronts the staging maintenance subdomain with cache invalidation capability
  • Deployment Pattern: Modified HTML is pushed to S3, then CloudFront cache is invalidated to serve fresh assets immediately

Example deployment command pattern (no credentials shown):

aws s3 cp staging-index.html s3://[bucket]/tools/maintenance/
aws cloudfront create-invalidation --distribution-id [DIST_ID] --paths "/tools/maintenance/*"

Google Apps Script Configuration

GAS serves as the serverless backend for maintenance operations. The script is deployed via clasp (Google Apps Script CLI) to the Apps Script project associated with the queenofsandiego.com property sheet.

Key GAS files modified:

  • BookingAutomation.gs - doPost handler routes incoming requests by action type. Added routing for action: 'log_maintenance'
  • MaintenancePersistence.gs - NEW FILE - handles task storage, notification scheduling, and state management
  • MaintenanceCalendar.gs - NEW FILE - integrates with Google Calendar API to create recurring maintenance events

The doPost routing pattern in BookingAutomation.gs:

if (e.parameter.action === 'log_maintenance') {
  return handleMaintenanceLogging(e);
}

Lambda & Email Delivery

Following the existing tips-box Lambda deployment pattern, we configured an email delivery function that:

  • Accepts notification payloads from GAS via HTTPS POST
  • Evaluates task criticality (CRITICAL, HIGH, MEDIUM, LOW)
  • Determines notification strategy (immediate vs. digest)
  • Publishes to SNS topic for SES email delivery

Lambda function configuration mirrors existing patterns:

  • Runtime: Node.js (matching existing deployments)
  • IAM Role: References existing execution role with SNS and SES permissions
  • Environment Variables: SNS topic ARN for maintenance notifications, sender email alias

Key Technical Decisions

Why Notification Batching by Priority?

Research from high-performing operations teams (referenced in DevOps practices and incident management literature) shows that alert fatigue significantly reduces response effectiveness. By implementing tiered notification logic, we:

  • Send CRITICAL tasks immediately (electrical hazards, safety issues)
  • Send HIGH-priority tasks within 2 hours (scheduling conflicts, charter preparation)
  • Batch MEDIUM and LOW tasks into a daily digest at 6 PM (routine maintenance, non-urgent repairs)

This approach reduces unnecessary notifications while ensuring urgent items receive attention in the appropriate timeframe.

Why Separate MaintenancePersistence.gs?

Separating persistence logic from booking automation follows the Single Responsibility Principle. This allows:

  • Independent testing of task storage logic
  • Reuse of persistence functions across multiple handlers
  • Easier maintenance as the maintenance feature grows
  • Clear API boundaries between modules

Why Google Calendar Integration?

The MaintenanceCalendar.gs creates calendar events for maintenance tasks, providing:

  • Visual scheduling of work in the team's shared calendar
  • Automatic conflict detection with charters and events
  • Notification integration via Google Calendar's native reminder system
  • Historical audit trail of all maintenance activities

Staging vs. Production Separation

For testing, all email notifications are sent to jadasailing@gmail.com instead of the production recipient list. This is controlled via an environment variable in the Lambda function and a feature flag in MaintenancePersistence.gs that checks the requesting domain.

Future production deployment will:

  • Create a separate GAS project for production maintenance logging
  • Use distinct Lambda environment configurations
  • Implement DNS switching via Route53 to control which backend receives requests

Code Deployment Process

GAS deployment uses clasp (CLI for Apps Script):

cd /Users/cb/Documents/repos/sites/queenofsandiego.com
clasp push

This deploys all modified .gs files to the Apps Script project. The script is deployed (not versioned), making changes immediately live. Staging HTML changes are deployed to S3 and invalidated in CloudFront.

What's Next

  • Calendar Integration Testing: Verify that recurring maintenance tasks create proper Google Calendar events with attendee notifications
  • Email Template Refinement: Design task-specific email templates that highlight critical information (equipment affected, estimated duration, dependencies)
  • Production Deployment: Create separate infrastructure for production maintenance notifications once staging validation is complete
  • Dashboard Enhancements: Add real-time task status visibility to the maintenance tool UI, showing which team members are assigned to which tasks