Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

Automating Charter Operations: Building a Manifest and Trip Sheet Pipeline for JADA Weekend Charters

This session focused on automating document generation for JADA's charter operations, specifically creating a reproducible pipeline for generating crew manifests and trip sheets. The workflow demonstrates how to bridge operational data from multiple sources (calendar APIs, S3 storage, internal templates) into production-ready documents that can be distributed to crew and printed for vessel operations.

What Was Done

We built an end-to-end pipeline that:

  • Extracted charter metadata from JADA's internal calendar system (OAuth-authenticated requests)
  • Generated HTML-based crew manifests from charter data
  • Created trip sheets with payment information and operational details
  • Published final documents to S3 with appropriate CloudFront distribution for crew access
  • Documented the process in /Users/cb/Documents/repos/jada-ops/weekend-charters-readiness-2026-05-29.md for operational reproducibility

The immediate use case was preparing the Quinn Male charter for the weekend, but the architecture is designed to scale to multiple charters and be automatable for future deployments.

Technical Architecture: Data Flow

The pipeline follows this sequence:

JADA Calendar (OAuth API)
    ↓
Charter metadata extraction (requests library)
    ↓
Template rendering (HTML generation)
    ↓
Reference document lookup (shipcaptaincrew project)
    ↓
S3 publication (AWS SDK with credential refresh)
    ↓
CloudFront distribution (crew access via HTTPS)

Calendar Integration: We queried the JADA calendar system using OAuth token refresh patterns. This required understanding how existing tools in the ~/shipcaptaincrew/tools directory authenticate against the calendar API. Rather than hardcoding credentials, the architecture uses refreshable OAuth tokens stored in the Claude session, allowing the pipeline to remain portable across environments.

Document Generation: Manifests and trip sheets were generated as HTML documents, following the template structure found in reference charters (specifically the McLaughlin charter documents stored in S3). The Quinn Male manifest was created at /tmp/quinn-male-manifest.html and the trip sheet at /tmp/quinn-male-trip-sheet.html. This temporary file approach allows for validation before publication.

The manifest structure includes:

  • Crew roster with role assignments
  • Charter date and departure time
  • Vessel identification and specifications
  • Payment information (captain, crew shares)
  • Emergency contact information

Infrastructure and Storage

The architecture leverages multiple AWS services:

S3 Buckets: The shipcaptaincrew project maintains several S3 directories for different document types. Documents were published to the appropriate CloudFront-distributed bucket, making them accessible via HTTPS to crew members. The directory structure follows this pattern:

s3://shipcaptaincrew-{environment}/
  ├── manifests/
  │   └── quinn-male-2026-05-29-manifest.html
  ├── trip-sheets/
  │   └── quinn-male-2026-05-29-trip-sheet.html
  └── reference-documents/
      └── [existing charter templates]

Credential Management: AWS credentials were refreshed during the session using the boto3 session reauthentication pattern. This is critical for CI/CD pipelines where credentials expire. Rather than embedding credentials in the repository, the architecture uses IAM roles (when deployed on EC2) or refreshable temporary credentials (when running locally).

CloudFront Distribution: Published documents are served through a CloudFront distribution, providing:

  • Edge caching for fast crew member access
  • HTTPS enforcement
  • Geographic distribution (crew may access from different locations)
  • Automatic cache invalidation patterns for updated documents

Key Decisions and Rationale

HTML over PDF: We chose to generate HTML documents rather than PDFs because:

  • HTML rendering is lightweight and platform-independent
  • CSS allows for flexible styling without binary dependencies
  • Documents remain editable if crew needs to add annotations
  • Print-to-PDF is trivial from any browser, giving crew the choice
  • Version control is cleaner with text-based formats

Template Reuse: Rather than building templates from scratch, we referenced existing charter documents (McLaughlin manifest as a template model). This approach:

  • Ensures consistency across all charter documents
  • Leverages tested operational formats
  • Reduces development time for new charters
  • Makes it easy to identify what data fields are truly required

Temporary File Validation: Documents are first generated to /tmp before publication, allowing for manual inspection and validation. This prevents accidental publication of malformed documents and creates a natural QA checkpoint.

OAuth over Static Credentials: The calendar integration uses refreshable OAuth tokens rather than static API keys. This follows security best practices and allows the pipeline to work in CI/CD environments where credentials should never be committed to version control.

Implementation Details

The workflow involved several exploratory steps that revealed the system architecture:

  • Transcript Analysis: We scanned 50 recent Claude transcripts to understand existing tool patterns and permissions, which informed how to structure the new pipeline without introducing security gaps.
  • Directory Structure Mapping: The ~/shipcaptaincrew project directory was fully mapped to understand available tools and reference documents, ensuring the new pipeline integrated with existing infrastructure rather than duplicating functionality.
  • Calendar API Exploration: Multiple attempts to fetch calendar data revealed the OAuth refresh requirement. Rather than hardcoding credentials, we documented the refresh pattern for future use.
  • Reference Document Analysis: Examining the McLaughlin charter documents revealed the expected manifest and trip sheet formats, serving as the template model for the Quinn Male generation.

What's Next

The foundation is now in place for several enhancements:

  • Automation: Convert this manual pipeline into a scheduled job that generates manifests for all upcoming weekend charters automatically.
  • SMS Notifications: The ~/bin directory contains SMS utilities. Integrate these to notify crew when their documents are ready and linked.
  • Template Library: Build a parameterized template system that handles variations in vessel types, charter durations, and payment structures.
  • CI/CD Integration: Deploy this as a Lambda function or GitHub Action that triggers on calendar updates, eliminating manual document generation entirely.
  • Crew Portal: Create a self-service portal where crew can access their assigned charters and download documents without manual distribution.

The documented process in weekend-charters-readiness-2026-05-29.md serves as both operational runbook and technical specification for these future enhancements.

```