Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

Publishing Charter Documentation to S3: Building a Reliable Manifest Pipeline for JADA Operations

During this development session, I built and deployed an automated pipeline to publish charter manifests and trip sheets to S3, enabling JADA's weekend operations team to access crew assignments and vessel readiness data without direct repository access. The implementation involved HTML document generation, AWS credential management, and content verification across live CloudFront distributions.

What Was Done

The core objective was to move charter documentation (crew manifests and trip sheets) from a local development environment into a production S3 bucket accessible via CloudFront. This required:

  • Extracting and templating charter data from existing reference documents
  • Generating structured HTML manifests and trip sheets
  • Publishing to S3 with proper CloudFront invalidation
  • Verifying content availability via live HTTP endpoints
  • Building reusable documentation patterns for future charters

The specific use case: Quinn Male's charter on 2026-05-29 required crew assignments, payment status, and vessel readiness information published to web-accessible URLs before the weekend operation began.

Technical Implementation

Document Generation

The pipeline created two complementary HTML documents:

  • /tmp/quinn-male-manifest.html — A crew manifest listing vessel assignments, crew names, positions, and contact information
  • /tmp/quinn-male-trip-sheet.html — A trip sheet documenting passenger capacity, payment status, departure times, and equipment readiness

These documents were templated based on existing reference charters (McLaughlin, Keely crew pages) to maintain consistent formatting and data structure. The HTML was intentionally simple and print-optimized, allowing operations staff to generate PDFs directly from the browser without backend dependencies.

Template extraction pattern:

1. Fetch reference document from S3 (e.g., /manifests/mclaughlin-2026-05-22.html)
2. Extract HTML structure, CSS styling, and data placeholders
3. Create local template with variable injection points
4. Populate with Quinn Male charter data from calendar events
5. Validate against existing structural requirements

Data Sourcing

Charter data was aggregated from multiple sources within the JADA ops ecosystem:

  • Calendar system — JADA Internal calendar events containing payment details, passenger counts, and vessel assignments (accessed via OAuth token refresh for authentication)
  • Reference documents — Existing charter manifests in the shipcaptaincrew S3 bucket as formatting templates
  • Local project files — Detailed project notes stored in /Users/cb/Documents/repos/agent_handoffs/projects/quinn-male-charter.md containing crew assignments and operational notes

The calendar proved to be the authoritative source for payment status and charter confirmation, avoiding the need for manual data entry.

Infrastructure and Deployment

S3 Publishing

Documents were published to the shipcaptaincrew S3 bucket under the manifests prefix:

  • s3://shipcaptaincrew/manifests/quinn-male-2026-05-29.html
  • s3://shipcaptaincrew/trip-sheets/quinn-male-2026-05-29.html

The publishing process required AWS credential reauthentication mid-session. Initial attempts failed due to expired session tokens; the solution was to explicitly refresh credentials before subsequent S3 calls:

# Reauthenticate AWS session before publishing
aws sts get-caller-identity

# Verify S3 bucket access
aws s3 ls s3://shipcaptaincrew/manifests/

# Publish manifests
aws s3 cp quinn-male-manifest.html s3://shipcaptaincrew/manifests/
aws s3 cp quinn-male-trip-sheet.html s3://shipcaptaincrew/trip-sheets/

This pattern ensures credentials remain valid across multiple API calls, critical for long-running development sessions.

CloudFront Distribution

The shipcaptaincrew S3 bucket is fronted by a CloudFront distribution, providing:

  • Global CDN caching for reduced latency
  • HTTPS enforcement for all manifests
  • Automatic cache invalidation support for updated documents
  • HTTP 200 responses for live documents, verified via curl

Live URLs follow the pattern: https://manifests.jada.tech/quinn-male-2026-05-29.html (exact distribution domain withheld for security).

Content Verification

Post-deployment verification checked both HTTP status and content accuracy:

# Verify CloudFront returns HTTP 200
curl -I https://manifests.jada.tech/quinn-male-2026-05-29.html

# Spot-check live content matches local copy
curl https://manifests.jada.tech/quinn-male-2026-05-29.html | grep "Quinn Male"

This two-stage verification (status + content) caught potential issues with incomplete uploads or stale CloudFront caches.

Key Architecture Decisions

Why Static HTML Over Dynamic Endpoints

Rather than building a backend API to generate manifests on-demand, the design chose static HTML files published to S3. Rationale:

  • Operations staff need reliable access without backend service uptime dependencies
  • Static files cache efficiently in CloudFront, reducing latency to operations team
  • No authentication required at read time — crew and passengers receive simple links
  • Documents are immutable per charter date, eliminating race conditions around concurrent updates
  • Compliance: Static files in S3 maintain audit trails automatically via CloudTrail

Credential Management in Development

The session required multiple credential reauthentications (OAuth tokens for calendar access, AWS session tokens for S3). The workflow:

  • Store AWS credentials in standard ~/.aws/credentials with session token support
  • Use boto3/AWS CLI's automatic credential chain rather than hardcoded tokens
  • Explicitly refresh session state when errors indicate token expiration
  • Never log credentials — use aws sts get-caller-identity to verify active session instead

This pattern scales to CI/CD pipelines by replacing local credentials with IAM role assumption.

Template-First Approach

Rather than inventing manifest format, the implementation extracted templates from existing, proven documents (McLaughlin, Keely charters). Benefits:

  • Consistent UX — crew and operations staff recognize familiar layout
  • Reduced design debt — no need to iterate on formatting
  • Compliance alignment — existing documents were already approved and tested
  • Faster implementation — focus on data integration rather than UI design

What's Next

This pipeline establishes the foundation for automated charter documentation. Future improvements:

  • Scheduled generation — Trigger manifest generation 48 hours pre-charter via Lambda, eliminating manual publication
  • Multi-charter batching