Implementing Real-Time Task Notifications for the Maintenance Tool: Architecture & Deployment Strategy

Overview: The Problem

The maintenance.queenofsandiego.com tool was missing a critical feature: visibility into newly added maintenance tasks. When Travis added tasks via the management interface, there was no way for the team (particularly Sergio) to be notified of these additions. This created a gap between task creation and task awareness, especially problematic for time-sensitive or high-criticality work items.

We needed a solution that would:

• Surface new tasks in real-time based on criticality
• Notify relevant team members (Sergio, operations) intelligently
• Respect staging vs. production concerns during development
• Integrate with existing infrastructure without major refactoring
• Leverage industry best practices for notification pacing

Architecture Decision: Why Lambda + Email Notifications

Rather than polling or building a custom notification system, we implemented a Lambda-based persistence layer that triggers email notifications based on task criticality. This approach was chosen because:

• Cost-effective: Lambda charges per invocation; idle time costs nothing
• Serverless scaling: No infrastructure to manage as task volume grows
• Email as the notification medium: Already understood by the team, supports digest strategies, and provides an audit trail
• Criticality-driven urgency: High-priority tasks trigger immediate notifications; lower-priority tasks can batch into end-of-day digests
• Integration with existing GAS infrastructure: Google Apps Script already handles booking automation; extending it for maintenance tasks maintains architectural consistency

Technical Implementation Details

1. Persistence Layer: MaintenancePersistence.gs

Created a new Google Apps Script file at:

/Users/cb/Documents/repos/sites/queenofsandiego.com/MaintenancePersistence.gs

This file handles:

• Storing task metadata in Google Sheets (the backing store for maintenance tasks)
• Tracking task creation timestamps and criticality levels
• Maintaining state to prevent duplicate notifications
• Queuing notifications for batch processing

The persistence layer uses Google Sheets as the data store because it's already integrated with the maintenance tool and provides natural audit trail capabilities through version history.

2. Calendar Integration: MaintenanceCalendar.gs

Created a new companion file at:

/Users/cb/Documents/repos/sites/queenofsandiego.com/MaintenanceCalendar.gs

This handles:

• Creating/updating the "Jada Maintenance" calendar in jadasailing@gmail.com
• Syncing high-priority maintenance tasks to the calendar as events
• Setting appropriate reminders based on task urgency
• Providing visual representation of maintenance schedules alongside booking calendars

We chose calendar integration for high-criticality items because it provides visibility in the team's existing workflow without requiring a new tool.

3. GAS Route Handler: BookingAutomation.gs Updates

Extended the existing BookingAutomation.gs doPost handler to recognize maintenance-related actions. Added routing logic to:

• Capture log_maintenance POST requests from the staging HTML
• Call MaintenancePersistence.logTask() with task data
• Trigger notification logic based on task criticality field
• Return success/error responses to the frontend

This approach reuses the existing GAS deployment rather than creating a separate Apps Script project, reducing maintenance surface area.

4. Frontend Enhancement: staging-index.html

Modified the maintenance tool UI at:

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

Key changes:

• Added a criticality dropdown field to task creation (Critical, High, Medium, Low)
• Modified the submit handler to POST to the GAS endpoint with action log_maintenance
• Added visual feedback (toast notifications) confirming task submission
• Implemented client-side validation for required fields

The staging HTML file is deployed to S3 at the production CloudFront distribution but marked as staging to allow testing without affecting live tasks.

Infrastructure & Deployment

S3 & CloudFront Configuration

The staging maintenance tool is deployed to:

• S3 Bucket: The production maintenance bucket (same origin)
• S3 Path: /tools/maintenance/staging-index.html
• CloudFront Distribution: The existing maintenance.queenofsandiego.com distribution
• URL: https://maintenance.queenofsandiego.com/tools/maintenance/staging-index.html

When ready to promote staging to production, we'll rename staging-index.html to index.html`, which CloudFront will serve with appropriate cache invalidation.

aws cloudfront create-invalidation \
  --distribution-id [DIST_ID] \
  --paths "/tools/maintenance/staging-index.html"