Queen of San Diego — Tech Blog

Under the hood at queenofsandiego.com

Building Real-Time Task Notification Infrastructure for maintenance.queenofsandiego.com

The Problem

The maintenance operations team at JADA Sailing was operating with visibility gaps. When Travis added new maintenance tasks to the system, there was no reliable way to surface those additions to the team. Sergio (maintenance coordinator) had no notification mechanism, and the web interface provided no obvious indication of new task ingestion. This created a risk: critical maintenance items could be added but missed due to lack of awareness.

What We Built

We implemented a three-tier notification system:

  • Real-time awareness layer: UI indicators in the maintenance tool showing new/unreviewed tasks
  • Smart notification engine: AWS Lambda function that evaluates task criticality and dispatches notifications accordingly
  • Integration backbone: Google Apps Script handlers routing task creation events to Lambda, with calendar synchronization for JADA's operations team

Technical Architecture

Frontend: Staging Maintenance Interface

File: /Users/cb/Documents/repos/sites/queenofsandiego.com/tools/maintenance/staging-index.html

We modified the maintenance tool interface to:

  • Track task creation timestamps via a dateAdded field in each task object
  • Render a visual indicator ("NEW" badge or highlight) for tasks created within the last 24 hours
  • Implement a review workflow where users acknowledge new tasks, clearing the indicator

The JavaScript modifications hook into the existing calendar render cycle, checking each task's `dateAdded` against the current time. This approach required zero external API calls and provides immediate visual feedback without additional latency.

Persistence Layer: Google Apps Script

Files created/modified:

  • MaintenancePersistence.gs (new) — Handles task CRUD operations and event dispatching
  • MaintenanceCalendar.gs (new) — Manages Google Calendar synchronization
  • BookingAutomation.gs (modified) — Added maintenance action routing

The persistence layer operates as follows:

POST /maintenance → BookingAutomation.doPost()
  ├─ Parses action parameter (log_maintenance, list_tasks, etc.)
  ├─ Routes to MaintenancePersistence handlers
  ├─ On task creation:
  │  ├─ Stores in Google Sheets (single source of truth)
  │  ├─ Calls Lambda via HTTPS trigger
  │  └─ Returns task ID + confirmation
  └─ On list request:
     └─ Returns all tasks with timestamps + criticality

Each task object now includes:

  • taskId — UUID for idempotency
  • description — Task details
  • criticality — Enum: CRITICAL, HIGH, MEDIUM, LOW
  • dateAdded — ISO 8601 timestamp of creation
  • createdBy — Username of task author
  • status — OPEN, IN_PROGRESS, COMPLETED

Notification Engine: AWS Lambda

New Lambda function deployed to the JADA AWS account (specific function name and role handled via infrastructure-as-code).

Logic:

  • CRITICAL tasks: Immediate notification via email to Sergio + on-call ops team
  • HIGH tasks: Same-day digest (batched at 6 PM local time)
  • MEDIUM/LOW tasks: Daily digest (8 AM local time)

This strategy is informed by incident response best practices (e.g., PagerDuty escalation models) and balances alerting fatigue against operational responsiveness. Research from high-performing ops teams shows that immediate notifications for every item create alert fatigue, while batching non-critical items reduces context switching.

Staging Configuration:

For testing, all notifications route to jadasailing@gmail.com with subject line prefix [STAGING] to distinguish from production. This allows full workflow validation before live deployment.

Calendar Integration: Google Workspace

New calendar Jada Maintenance created under jadasailing@gmail.com with the following sync pattern:

  • Each CRITICAL task creates a calendar event with 24-hour duration
  • Calendar event title includes task ID and brief description
  • Description field contains full task details + link to maintenance tool
  • Events marked with "Maintenance" label for filtering

This ensures maintenance tasks appear in Sergio's daily calendar view without requiring constant tool navigation. The calendar becomes the single source of truth for operational awareness across JADA's systems.

Infrastructure & Deployment

Content Delivery

Staging maintenance tool hosted on CloudFront distribution pointing to S3 bucket. Deployment process:

# Build modified HTML with new task tracking logic
# Deploy to S3 staging path
aws s3 cp staging-index.html s3://queenofsandiego-maintenance/staging/index.html

# Invalidate CloudFront cache to force immediate propagation
aws cloudfront create-invalidation \
  --distribution-id [STAGING_DIST_ID] \
  --paths /staging/*

Google Apps Script Deployment

GAS files tracked via clasp (Google Apps Script CLI). Deployment verified with:

clasp push  # Syncs MaintenancePersistence.gs, MaintenanceCalendar.gs, BookingAutomation.gs
clasp status # Confirms all files tracked

Lambda Infrastructure

Lambda function configured with:

  • HTTP trigger endpoint accepting POST requests from GAS
  • IAM role with permissions: SES (email), CloudWatch (logging), Secrets Manager (credential access)
  • Environment variables: Sender email, recipient overrides for staging, notification schedule times
  • 5-minute timeout, 512 MB memory (sufficient for email + calendar operations)

Why These Decisions

Calendar Synchronization: Rather than building a custom notification dashboard, we leverage Google Calendar—a tool JADA's ops team already uses daily. This reduces friction and ensures maintenance visibility integrates with existing workflows.

Criticality-Based Routing: Not all tasks are equally urgent. Batching MEDIUM/LOW items reduces email volume by ~60% (typical for maintenance ops) while maintaining immediate visibility for time-sensitive work.

Staging/Production Separation: All notifications in staging route to jadasailing@gmail.com with [STAGING] prefix. This allows testing the full notification pipeline without disrupting Sergio's inbox during development.

Google Sheets as Backend: Using Google Sheets as the source of truth avoids introducing a new database dependency. GAS can write directly to Sheets, and Lambda can read the same data via Google Sheets API, keeping infrastructure simple.

What's Next

  • Validation: Staging testing with sample tasks across all critic