Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

Automating Charter Document Generation and S3 Publication for JADA Weekend Operations

This session focused on building an automated pipeline to generate and publish charter-related documents (manifests and trip sheets) for JADA's weekend operations. The goal was to reduce manual document handling and ensure consistent, timely delivery of crew and passenger information to S3 for downstream systems.

What Was Done

We built a complete document generation and publication workflow that:

  • Extracted charter booking data from the JADA calendar system via OAuth-authenticated API calls
  • Generated HTML manifest and trip sheet documents from charter data
  • Published generated documents to S3 for CDN distribution
  • Created a readiness report tracking all weekend charters and their document status
  • Established a repeatable pattern for future charter document automation

Technical Details: Calendar Data Extraction

The initial challenge was accessing JADA's calendar system securely. Rather than hardcoding credentials, we implemented OAuth token refresh within the data fetch process:

requests.get(
    'https://calendar.jada.local/api/events',
    params={
        'startDate': '2026-05-29T00:00:00Z',
        'endDate': '2026-05-31T23:59:59Z',
        'status': 'confirmed'
    },
    headers={'Authorization': f'Bearer {oauth_token}'}
)

This approach allows the script to:

  • Query the calendar API for a specific date range without hardcoding authentication
  • Filter for confirmed charters only (avoiding draft or cancelled bookings)
  • Handle token expiration gracefully through automatic refresh mechanisms
  • Scale across multiple weekend queries without credential rotation

By analyzing existing tool implementations in the codebase, we discovered that similar calendar queries were already being made from other systems. We followed the same OAuth pattern rather than introducing a new authentication method, ensuring consistency across the infrastructure.

Document Generation Architecture

Charter documents follow a template-based HTML generation pattern. For the Quinn Male charter, we generated two documents:

  • Manifest (/tmp/quinn-male-manifest.html) — Contains passenger list, dietary requirements, emergency contacts, and crew assignments
  • Trip Sheet (/tmp/quinn-male-trip-sheet.html) — Contains itinerary, departure/return times, equipment list, and weather briefing information

The generation process involved:

  1. Fetching raw charter data from the calendar API
  2. Extracting payment status from calendar event metadata
  3. Referencing existing charter templates from the shipcaptaincrew project (/Users/cb/Documents/repos/shipcaptaincrew/)
  4. Rendering HTML using the reference templates as examples
  5. Validating document structure before publication

We examined historical manifests (specifically the McLaughlin charter manifest) to ensure our generated output matched the established format, maintaining consistency for crew and operations teams.

S3 Publication Pipeline

Generated documents are published to S3 with the following structure:

s3://jada-charters/2026-05-29/quinn-male-manifest.html
s3://jada-charters/2026-05-29/quinn-male-trip-sheet.html

Key decisions for the publication pipeline:

  • Date-based prefixing — Documents are organized by charter date, making it easy to retrieve all materials for a given weekend
  • Public-read ACLs — Manifests and trip sheets are readable by crew and operations staff, but write access is restricted to the automation service
  • HTML format in S3 — Rather than storing JSON or CSV, we publish ready-to-display HTML, eliminating the need for downstream rendering
  • AWS credential refresh — The publication process handles session re-authentication when credentials expire, allowing long-running batch operations

The S3 bucket is likely fronted by CloudFront for faster distribution to crew members accessing documents on limited bandwidth connections (common on boats), though the specific CloudFront distribution ID was not modified during this session.

Data Integration and Readiness Reporting

A comprehensive readiness report was generated at /Users/cb/Documents/repos/jada-ops/weekend-charters-readiness-2026-05-29.md, documenting:

  • All confirmed charters for the weekend (initially required scanning extended date ranges to locate charters 1-3)
  • Which charters had manifests generated and published
  • Which charters had trip sheets completed
  • Payment status and crew confirmations from calendar metadata
  • Any missing or incomplete documents requiring manual intervention

This report serves as a checklist for operations staff and provides a record of automation success or failure.

Key Infrastructure and Project References

The work integrated with several existing projects:

  • jada-ops — Repository for JADA operations scripts and reports (/Users/cb/Documents/repos/jada-ops/)
  • shipcaptaincrew — Template library and reference documents for charter information (/Users/cb/Documents/repos/shipcaptaincrew/)
  • agent_handoffs — Project tracking system with charter-specific handoff documentation (/Users/cb/Documents/repos/agent_handoffs/projects/quinn-male-charter.md)

By keeping templates and reference documents in shipcaptaincrew and automation logic in jada-ops, we maintain separation of concerns: the template library is source-of-truth for document format, while jada-ops orchestrates the generation and publication process.

Key Decisions and Rationale

  • HTML over JSON storage — Publishing ready-to-display HTML eliminates rendering delays and ensures formatting consistency across all clients consuming the documents
  • OAuth for calendar access — Rather than service account credentials, we used the existing OAuth flow to ensure the automation respects the same permission model as manual calendar access
  • Date-based S3 organization — This structure aligns with how operations staff think about charters (by weekend/date) and simplifies querying for a specific date range
  • Template-driven generation — By using reference documents as templates, new charter types can be added without rewriting the generation logic

What's Next

Future iterations could:

  • Automate publication of documents via email or SMS to crew (infrastructure for this may already exist in ~/bin SMS utilities)
  • Add pre-flight validation to ensure all required fields are populated before document generation
  • Create a Lambda function to trigger document generation automatically when charters transition to confirmed status in the calendar
  • Integrate with crew availability systems to cross-check crew assignments against confirmed availability
  • Add document versioning to track manifest updates if charter details change between generation and departure

This foundation provides a scalable pattern for automating any charter-related document generation, making it easy to add new document types or extend the workflow to cover additional charters beyond weekends.

```