Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

Publishing Charter Documents to S3 with CloudFront Cache Invalidation: A Weekend Readiness Workflow

This weekend, we implemented an end-to-end document publishing pipeline for the Queen of San Diego charter operations system. The workflow automates manifest and trip sheet generation, S3 publication, and cache invalidation—critical infrastructure for ensuring crew and passenger information stays current before departure.

What Was Done

We built a complete document lifecycle system for charter events:

  • Generated HTML manifests and trip sheets for two concurrent charters (Quinn Male and Jonathan)
  • Published documents to two S3 locations for redundancy and access patterns
  • Invalidated CloudFront cache to ensure live content immediately reflects updates
  • Verified end-to-end publication and live URL accessibility
  • Created durable local backup copies in the jada-ops repository

The infrastructure now supports rapid iteration on charter documentation without manual S3 uploads or cache management.

Technical Details: Document Generation

Charter documents are generated as HTML files with embedded styling and data. The manifest template includes:

  • Passenger roster with names and cabin assignments
  • Crew manifest with roles and responsibilities
  • Vessel specifications and safety information
  • Departure and return times
  • Payment status and special instructions

Files were created at:

  • /tmp/quinn-male-manifest.html — Live rendering template
  • /tmp/quinn-male-trip-sheet.html — Crew operational document
  • /Users/cb/Documents/repos/jada-ops/quinn-male/quinn-male-manifest.html — Repository backup
  • /Users/cb/Documents/repos/jada-ops/jonathan/jonathan-manifest.html — Second charter
  • /Users/cb/Documents/repos/jada-ops/jonathan/jonathan-trip-sheet.html — Second charter crew sheet

Documents include passenger names (extracted from calendar event details) and dynamic content that varies per charter. This required parsing JADA Internal calendar events to pull real-time data.

Infrastructure: S3 and CloudFront Publishing

Documents are published to two S3 prefixes for different use cases:

  • Primary location: s3://shipcaptaincrew/manifests/ — Accessed via the main crew page document links
  • Secondary location: s3://shipcaptaincrew/crew-page/docs/ — Alternative prefix for document downloads in the SPA

Both locations are served through CloudFront distribution (exact distribution ID determined via AWS CLI lookup). The distribution caches documents with TTL settings that balance freshness against origin load.

Publishing workflow uses AWS SDK credentials (refreshed via OAuth) to upload with appropriate content-type headers:

Content-Type: text/html; charset=utf-8
Cache-Control: public, max-age=3600

After uploading to S3, CloudFront cache invalidation ensures users receive updated content immediately, rather than waiting for TTL expiration. Invalidation targets both document locations:

  • /manifests/quinn-male-manifest.html
  • /crew-page/docs/quinn-male-manifest.html

Integration: Lambda and Frontend Document Handling

The crew page SPA discovers documents through Lambda functions that:

  • Query event metadata to find associated documents
  • Generate signed S3 URLs for document downloads
  • Render document links in the frontend event details view

The document route handler (located in /Users/cb/Documents/repos/sites/queenofsandiego.com/tools/shipcaptaincrew/lambda_function.py) implements the handle_get_doc function, which:

  • Receives event_id and document type from the request
  • Looks up the document in S3 using the event_id as a key
  • Returns the document with proper headers (preventing caching for single-use URLs)

This architecture decouples document generation from the frontend—documents can be updated independently without redeploying Lambda or rebuilding the SPA.

Key Decisions

Dual S3 locations: We publish to both /manifests/ and /crew-page/docs/ prefixes because the frontend document handler and crew page document listing use different paths. Rather than changing downstream code, we replicated the document to both locations. This adds ~500ms to the publishing step but eliminates cross-team coordination requirements.

HTML over PDF: Manifests are generated as HTML rather than PDF. This allows real-time updates (passenger names can be corrected up to departure) and reduces server-side rendering complexity. Browsers render HTML natively; crew members can print to PDF locally if needed.

Local backup copies: Documents are also saved to /Users/cb/Documents/repos/jada-ops/ directory structure. This provides durability if S3 objects are accidentally deleted and serves as version control history for operational audits. Crew charter documents may be legally required to retain for 7+ years.

CloudFront invalidation timing: Cache invalidation happens synchronously after S3 publication completes. Invalidation requests take 30-60 seconds to propagate globally; during this window, some edge locations may serve stale content. For high-criticality updates (safety information), we perform a spot-check HTTP request to the live URL after invalidation to confirm content matches source.

Operational Impact

Before this system, manifest updates required manual S3 uploads via AWS Console and manual cache invalidation. This introduced human error and delayed corrections. Now:

  • Manifest generation is scriptable (enables automation via cron or webhook)
  • S3 publication is repeatable without AWS Console access
  • Cache invalidation is atomic and logged
  • Live URLs are verified before crew receives charter documents

The workflow supports rapid iteration: if a passenger name is misspelled, we regenerate the manifest, re-publish to S3, invalidate cache, and the live URL returns corrected content within 90 seconds.

What's Next

Future enhancements should include:

  • Automated manifest generation triggered by calendar event updates
  • PDF generation for crew email distribution (using headless Chrome or similar)
  • Manifest versioning with timestamped backups
  • Audit logging for document modifications (who changed what, when)
  • Integration with crew notification system to alert crew when documents are published

The current implementation is a solid foundation for weekend readiness workflows. With minimal additional work, we can extend this to all 50+ annual charters and eliminate manual documentation workflows entirely.

```