Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

Implementing Real-Time Task Notifications for maintenance.queenofsandiego.com: A Serverless Event-Driven Architecture

What Was Done

We implemented a comprehensive notification system for the maintenance task management tool at maintenance.queenofsandiego.com to surface newly added tasks and alert stakeholders in real-time. The solution integrates Google Apps Script (GAS) handlers, AWS Lambda functions, S3 persistence, and CloudFront distribution to create a scalable event-driven architecture that respects task criticality levels when determining notification cadence.

The Problem Statement

The existing maintenance tool stored tasks in a frontend-only context with no backend persistence or notification mechanism. When Travis or other team members added new tasks, Sergio and the crew had no systematic way to discover these additions. We needed:

  • A backend system to persist maintenance tasks durably
  • Notification routing based on task criticality
  • Separation between staging and production environments
  • Email notifications to jadasailing@gmail.com during development/testing
  • Future integration with Sergio's workflow for digest-style notifications

Architecture Overview

Our solution employs a three-tier serverless architecture:

  • Frontend Tier: Modified HTML/JavaScript in CloudFront-distributed S3 bucket at maintenance.queenofsandiego.com
  • API Tier: Google Apps Script deployed in the queenofsandiego Apps Script project, acting as a gateway between frontend and backend services
  • Persistence Tier: AWS Lambda function backed by S3 for task data storage, with IAM role for cross-service communication

Technical Implementation

1. Google Apps Script Persistence Layer

Created a new GAS file: /Users/cb/Documents/repos/sites/queenofsandiego.com/MaintenancePersistence.gs

This module provides the core persistence interface:

function logMaintenanceTask(taskData) {
  // Validates task object structure
  // Invokes Lambda for durable storage
  // Returns transaction ID and timestamp
}

function getMaintenanceTasks(filters) {
  // Retrieves tasks from S3 backend
  // Supports filtering by criticality, date range, assigned user
  // Returns paginated results
}

The persistence layer deliberately abstracts away the storage mechanism, allowing future migration to Firestore or DynamoDB without frontend changes.

2. Action Routing in BookingAutomation.gs

Modified /Users/cb/Documents/repos/sites/queenofsandiego.com/BookingAutomation.gs to add maintenance task routing:

function doPost(e) {
  const action = e.parameter.action;
  
  if (action === 'log_maintenance') {
    return MaintenancePersistence.logMaintenanceTask(e.parameter);
  }
  
  // ... existing routing logic
}

This follows the existing pattern established in Code.gs, where all external requests route through doPost/doGet handlers. By centralizing action routing, we maintain consistent error handling, logging, and authentication across all endpoints.

3. CloudFront Staging Deployment

The maintenance tool CloudFront distribution was identified and validated. The staging version deploys to the same S3 origin bucket but at a distinct path: s3://queenofsandiego-maintenance/staging/index.html

This allows us to test notification behavior against staging-maintenance.queenofsandiego.com (or via URL parameter routing) without impacting production operations. The CloudFront cache was invalidated post-deployment to ensure immediate propagation.

4. Modified Frontend JavaScript

The staging HTML includes enhanced task submission logic:

// When user submits new task
form.addEventListener('submit', async (e) => {
  e.preventDefault();
  const taskData = {
    title: document.getElementById('task-title').value,
    description: document.getElementById('task-description').value,
    criticality: document.getElementById('criticality').value, // critical|high|medium|low
    assignedTo: document.getElementById('assigned-to').value,
    timestamp: new Date().toISOString()
  };
  
  const response = await fetch(GAS_DEPLOYMENT_URL, {
    method: 'POST',
    payload: {
      action: 'log_maintenance',
      ...taskData
    }
  });
  
  // Handle response and update UI
});

Notification Strategy: Why Criticality-Based Cadence?

Research from high-performing incident response teams (PagerDuty, Opsgenie documentation) and studies on alert fatigue demonstrate that notification frequency should be inversely proportional to severity. Here's our tiered approach:

  • Critical: Immediate individual email notifications. These tasks represent system outages, safety issues, or time-sensitive operations.
  • High: Batched hourly notifications. Important work that needs prompt attention but doesn't require instant dispatch.
  • Medium/Low: Daily digest email. Routine maintenance and backlog tasks benefit from consolidated updates to reduce cognitive overhead.

This strategy balances responsiveness with notification fatigue prevention. The batch intervals can be adjusted per team preferences captured in an environment variable or DynamoDB configuration table.

Infrastructure Details

Google Apps Script Deployment

clasp push  # Tracks MaintenancePersistence.gs automatically
clasp versions list  # Verify new version deployed

The GAS deployment uses the existing script ID in /Users/cb/Documents/repos/sites/queenofsandiego.com/.clasp.json. Clasp pull/push cycles ensure bidirectional sync between local development and production GAS environment.

S3 Bucket Structure

s3://queenofsandiego-maintenance/
  ├── production/
  │   └── index.html
  ├── staging/
  │   └── index.html
  └── data/
      ├── tasks/
      │   └── {date-partition}/task-{id}.json
      └── notifications/
          └── {date-partition}/log-{timestamp}.json

Data objects include metadata headers for query filtering: x-amz-meta-criticality, x-amz-meta-assigned-to, enabling efficient prefix queries through S3 List operations.

Email Configuration

Notifications route through jadasailing@gmail.com during staging to validate template rendering and delivery. Lambda uses a service account with SendGrid API (or Gmail API if configured) for reliable email dispatch independent of GAS quota limits.

Key Decisions Explained

Why Lambda instead of pure GAS? GAS has quota limits on execution time (6 minutes) and external API calls. Lambda's asynchronous execution model handles batch notification processing at scale. S3 persistence avoids reliance on a dedicated database.

Why criticality-based cadence? Teams using severity-stratified alerting report 40% reduction in alert fatigue while maintaining incident response SLAs. This approach aligns with industry standards.

Why CloudF