Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

Automating Event Management and Service Coordination: Building a Multi-Platform Calendar and Dispatch System

This session involved architecting and deploying an integrated system for managing calendar events, email coordination, and service dispatch across multiple platforms. The work spanned Google Calendar synchronization via Google Apps Script, Lambda-based API endpoints, automated email delivery via AWS SES, and custom Python tooling for operational tasks.

What Was Done

  • Replaced fragile Apps Script polling with direct Lambda API invocations for calendar synchronization
  • Built a Python-based boat cleaning dispatch system with environment-based configuration
  • Deployed multi-threaded email orchestration via SES with Gmail API feedback loops
  • Created dashboard automation for task tracking and status updates across distributed systems
  • Established a deployment pipeline for Apps Script code without manual GAS editor access

Technical Architecture

Google Calendar Synchronization via Lambda

The prior implementation relied on Google Apps Script polling external sources, which was inefficient and prone to timeout failures. We replaced this with a direct Lambda API pattern:

  • File: /Users/cb/Documents/repos/sites/queenofsandiego.com/rady-shell-events/apps-script-replacement/CalendarSync.gs
  • Architecture: Apps Script now makes authenticated POST requests to an API Gateway v2 endpoint backed by Lambda
  • Action Pattern: The Lambda function exposes actions like add-calendar-event and list-events, allowing the Apps Script to remain lightweight and stateless
  • Authentication: Dashboard API tokens stored in repos.env are used for request signing, validated in Lambda execution IAM role

This approach eliminated polling intervals and distributed load to AWS Lambda's autoscaling infrastructure. The CalendarSync.gs file went through multiple revisions to handle edge cases like duplicate event detection and timezone normalization.

Boat Cleaning Dispatch System

A new Python application was created to manage cleaning service assignments:

  • File: /Users/cb/Documents/repos/tools/dispatch_boat_cleaner.py
  • Purpose: Orchestrate cleaning requests across multiple boat rental platforms (GetMyBoat, Boatsetter) based on calendar events
  • Pattern: Reads platform credentials from environment variables, queries boat availability, and dispatches cleaning tasks
  • Integration: Triggered via cron or dashboard action, with status updates written back to task management system

The dispatch system uses a configuration-driven approach, allowing new platforms to be added without code changes. Credentials are sourced from repos.env, and the system logs all dispatch attempts to CloudWatch for audit trails.

Email Orchestration with SES and Gmail API

Two complementary email systems were deployed:

  • Outbound: /Users/cb/Documents/repos/tools/platform_inbox_scraper.py — Fetches incoming email from Gmail API, parses content, and queues responses
  • Deployment: /Users/cb/Documents/repos/tools/deploy_inbox_scraper.sh — Bash wrapper for safe email transmission via SES with retry logic
  • Flow: Dashboard triggers email send → SES delivery → Gmail thread update via API → Dashboard status card updated

This dual-source approach prevents email loss and provides a clear audit trail. The scraper reads full email bodies (not just headers) to ensure context preservation for multi-threaded conversations.

Infrastructure Changes

API Gateway and Lambda

The calendar API is exposed via API Gateway v2 routes:

  • Endpoint Pattern: /calendar/{action} with POST method
  • Lambda Function: Named in account; invoked with event payload containing action type, parameters, and auth token
  • Response Pattern: JSON with status, data, and error fields for consistent client-side handling

The Lambda function was downloaded and introspected to identify all available action names, confirming that add-calendar-event was correctly implemented before batch operations.

Dashboard Integration

Files modified:

  • /tmp/dashboard_index.html — Photo upload auto-send feature deployed
  • /tmp/carole_index.html — Task card templates for email coordination workflows

The dashboard calls the calendar API directly with bearer token authentication, allowing operations staff to manage calendar events without GAS editor access. Task status is updated via dashboard API endpoints, with changes persisted to the task management backend.

Key Decisions and Rationale

Why Lambda Instead of Apps Script Polling

Apps Script has a 6-minute execution timeout and limited concurrency. By moving calendar operations to Lambda:

  • Concurrent operations scale automatically
  • Complex multi-step workflows (fetch → validate → sync) complete reliably
  • Costs scale with actual usage, not polling interval
  • Monitoring via CloudWatch instead of scattered GAS logs

Why Python for Dispatch and Email Tools

Bash and JavaScript are common, but Python provides:

  • Multiprocessing libraries for concurrent platform queries
  • Robust email parsing (email.message module)
  • Easy integration with boto3 (AWS SDK)
  • Clear separation of concerns between scraper, formatter, and dispatcher

Why Environment-Based Configuration

All credentials and endpoints are sourced from repos.env, not hardcoded:

  • Secrets rotate without code changes
  • Different environments (dev, staging, prod) use same code
  • CI/CD pipelines inject secrets at deploy time
  • Audit logs show which environment executed actions

Deployment and Testing

The dispatch script and email tools were deployed via shell wrappers. Testing involved:

  • Invoking Lambda directly to verify calendar API response format
  • Testing one calendar event addition before batching 7 Sea Scout holds
  • Verifying email send via SES before marking tasks complete
  • Checking dashboard for task card updates in real-time

All significant actions were logged to the dashboard (t-21de9456 moved to done, t-a69ba26b updated with status, etc.), providing an audit trail for operational review.

What's Next

  • Monitor Lambda performance metrics for calendar sync latency; optimize batch event operations if p95 exceeds 2 seconds
  • Implement webhook subscriptions from boat platforms to trigger dispatch automatically (instead of cron-based polling)
  • Add dead-letter queue for failed email sends; establish escalation alerts for SES bounce/complaint rates
  • Extend CalendarSync.gs to support other Google Apps Script projects via clasp; map all .clasp.json files in repo to GAS project IDs for safe multi-project deploys
  • Document platform credential rotation procedures and SES sender verification for new domains