Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

Automating Charter Operations: Building a Manifest Generation Pipeline for JADA Weekend Bookings

Over this development session, I built an automated pipeline to generate and publish charter manifests and trip sheets for JADA's weekend operations. The workflow extracts booking data from the operations calendar, generates HTML documents, and publishes them to S3 for crew access. Here's how it works and why we structured it this way.

What Was Done

The session focused on three core deliverables:

  • Extracted charter booking details from the JADA operations calendar (OAuth-authenticated Google Calendar API)
  • Generated two HTML documents per charter: a captain's manifest and a crew trip sheet
  • Published these documents to S3 buckets for immediate crew access
  • Created a weekend readiness report consolidating all active charters

The specific charter processed was the Quinn Male booking, which required pulling payment details, crew assignments, and vessel information to populate the manifest templates.

Technical Architecture

Data Sources and API Integration

The pipeline authenticates with Google Calendar using OAuth tokens stored in the JADA operations infrastructure. Rather than hardcoding credentials, the authentication flow refreshes tokens automatically when they expire:


# Calendar queries filtered by date range and event properties
Fetch JADA Internal calendar events for weekend date range
Parse event details: booking name, vessel, crew assignments, payment status
Extract custom fields from event descriptions and extended properties

This approach ensures the system pulls live data without requiring manual updates or static configuration files.

Document Generation Pipeline

Two separate HTML templates were populated with charter-specific data:

  • Manifest Document (/tmp/quinn-male-manifest.html): Captain's manifest with vessel specs, crew list, safety procedures, and passenger manifest sections
  • Trip Sheet (/tmp/quinn-male-trip-sheet.html): Crew briefing document with itinerary, weather conditions, equipment checklists, and communication protocols

The templates follow the pattern established in the shipcaptaincrew project's reference documents. Rather than maintaining separate template files, the generation logic structures data to match existing crew documentation standards.

S3 Publication Strategy

Generated documents publish to JADA's S3 infrastructure with the following path structure:


s3://jada-operations-docs/charters/[charter-name]/manifest.html
s3://jada-operations-docs/charters/[charter-name]/trip-sheet.html

Files are published with public read permissions (via CloudFront distribution), allowing crew members to access documents via direct URLs without authentication. This eliminates the need for separate credential distribution and keeps critical operational documents accessible even if the main systems experience outages.

Infrastructure and Infrastructure-as-Code Decisions

AWS Credentials and Session Management

Rather than storing AWS credentials in the application, the pipeline uses AWS SigV4 authentication with temporary session credentials. The session lifecycle is managed through boto3, with automatic credential refresh:


# Reauthenticate AWS session when credentials expire
Refresh IAM session token
Verify S3 bucket access permissions
Retry failed uploads with fresh credentials

This pattern is more secure than storing long-lived access keys and prevents credential leakage in logs or version control.

CloudFront Distribution Configuration

Documents are served through CloudFront rather than direct S3 access for two reasons:

  • Performance: Edge caching reduces latency for crew members accessing documents from different locations
  • Security: CloudFront acts as a facade, allowing us to implement signed URLs or IP restrictions without modifying bucket policies directly

The distribution is configured with HTTPS enforcement and points to the jada-operations-docs S3 bucket origin.

Route53 DNS Strategy

A CNAME record routes charters.jada.internal to the CloudFront distribution, providing a stable URL for crew documentation that doesn't change if we need to migrate S3 buckets or update the distribution.

Key Technical Decisions

Why OAuth Over Service Accounts

The calendar integration uses OAuth tokens rather than service account keys. This decision enables:

  • Audit trails: Calendar API logs attribute actions to specific user accounts, not generic service identities
  • Permission boundaries: OAuth scopes restrict what the pipeline can access (read-only to specific calendars)
  • Token rotation: Short-lived tokens reduce blast radius if credentials are compromised

Why Template-Based Generation Over Database Queries

Rather than querying a centralized charter database, the pipeline extracts data directly from calendar events and custom fields. This approach trades some redundancy for operational flexibility:

  • Single source of truth: calendar events remain the authoritative booking record
  • Decoupling: manifest generation doesn't require changes to booking systems
  • Resilience: calendar exports work even if downstream systems fail

Why HTML Over PDF

Documents are generated as HTML rather than PDF for several practical reasons:

  • Mobile-friendly: Crew can view documents on smartphones without special software
  • Searchable: HTML preserves text for browser search functionality
  • Lightweight: No external PDF rendering dependencies or libraries to manage
  • Version control-friendly: HTML diffs are human-readable if documents are tracked in Git

Operational Workflows Created

The session also documented the complete weekend readiness process in /Users/cb/Documents/repos/jada-ops/weekend-charters-readiness-2026-05-29.md. This guide consolidates:

  • Calendar event parsing logic
  • Manifest template population steps
  • S3 publication procedures
  • Verification and QA checklist

The guide serves as both documentation and the foundation for automating this process further (e.g., via Lambda functions triggered on calendar event creation).

What's Next

Future iterations should focus on:

  • Lambda automation: Trigger manifest generation automatically when calendar events are created, eliminating manual document generation
  • Webhook notifications: Send SMS to crew when documents are published, using the existing SMS utility in ~/bin
  • Template versioning: Store manifest templates in version control alongside the generation code
  • Batch processing: Generate manifests for multiple charters in a single operation during peak booking periods

This foundation enables scaling from manual document generation to a fully automated charter operations workflow.

```