Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

Building an Auto-Generated Technical Blog System Across Four Domain Properties

What Was Done

Implemented a complete automated technical documentation system that captures granular development activity across four properties (queenofsandiego.com, sailjada.com, dangerouscentaur.com, and burialsatseasandiego.com) and publishes to corresponding tech blog subdomains. The system uses Claude Code session transcripts as the data source, automatically extracts meaningful work items, and generates detailed technical posts without manual intervention.

Architecture Overview

The solution consists of three primary components:

  • Stop Hook: Executes automatically when a Claude Code session ends, capturing the session transcript
  • Infrastructure Initialization: Sets up S3 buckets, CloudFront distributions, DNS records, and ACM certificates for each tech blog domain
  • Blog Generator: Parses session transcripts, extracts tool usage patterns and file modifications, and generates granular technical posts

Infrastructure Setup

For each of the four properties, we provisioned:

  • S3 Buckets: Static site hosting buckets (qos-tech, jada-tech, dc-sites, bats-tech)
  • CloudFront Distributions: Global CDN with AWS-managed SSL/TLS certificates for performance and security
  • DNS Records: CNAME or A records pointing to CloudFront distributions
  • ACM Certificates: Wildcard certs for *.queenofsandiego.com and *.sailjada.com; individual certs for dangerouscentaur.com and burialsatseasandiego.com subdomains

Domain-Specific Details:

  • queenofsandiego.com & sailjada.com: Leveraged existing wildcard ACM certificates (*.queenofsandiego.com and *.sailjada.com) managed in us-east-1 region for CloudFront compatibility
  • dangerouscentaur.com: Uses existing wildcard CloudFront distribution (E2Q4UU71SRNTMB) on dc-sites S3 bucket; tech subdomain added as alternate domain name
  • burialsatseasandiego.com: DNS hosted at GoDaddy; ACM certificate validation via DNS CNAME records configured through GoDaddy API integration

Session Transcript Processing

The blog generator processes Claude Code session transcripts (stored as JSONL format in ~/.claude/sessions/) to extract technical work. The transcript structure includes:

  • Tool use entries: Each tool invocation (read_file, write_file, execute_command) is logged with timestamps
  • File operations: Captures all file modifications, creations, and edits with exact paths
  • Command execution: Records shell commands run during the session for infrastructure changes
  • User messages: Maintains context for why work was performed

The generator parses this data to create a granular narrative: instead of "Updated website files," it reports "Modified /Users/cb/Documents/repos/sites/queenofsandiego.com/notes/email_birthday_sail_2026.html to fix email template validation." This level of detail is essential for stakeholders like Sergio to understand the actual work performed.

File Organization & Navigation

Tech blogs are integrated into the "Ship's Papers" menu on each property's main site. The navigation structure adds a "Technical Blog" link that points to the respective tech subdomain:

<li><a href="https://tech.queenofsandiego.com">Technical Blog</a></li>

This makes technical documentation discoverable for anyone reviewing the property, with no additional maintenance required.

Key Technical Decisions

Why JSONL Transcripts? Claude Code stores session data in JSONL (JSON Lines) format, one JSON object per line. This format allows us to stream large transcripts without loading the entire file into memory and makes it simple to parse tool invocations sequentially.

Why Granular Posts Instead of Summaries? High-level summaries obscure the actual work performed. By extracting exact file paths, function names, and command sequences, we create an audit trail that demonstrates the depth and breadth of engineering work. This is particularly valuable when stakeholders need to understand the scope of changes made to critical systems.

Why Automatic On Session End? The Stop hook executes via Claude Code's built-in lifecycle, ensuring no work is missed. There's no manual step to remember, reducing the chance of stale or incomplete documentation.

Why Different Certificate Strategies? We reused existing wildcard certs where available (queenofsandiego.com, sailjada.com) to reduce certificate management overhead. For properties with different DNS providers (dangerouscentaur at Namecheap, burialsatseasandiego at GoDaddy), we used CloudFront wildcard distributions and DNS validation respectively, matching each provider's capabilities.

Security & Credential Handling

The blog generator implements strict filters to prevent credential exposure:

  • Environment variables containing API keys, tokens, or passwords are excluded from generated posts
  • File paths to credential storage (e.g., .env, credentials.json) are noted but contents are never published
  • Command examples are sanitized: "aws s3 cp index.html s3://qos-tech/" is shown, but redacted commands are never included
  • User context is preserved when safe (e.g., "configured Route53 for sailjada.com") but personally identifying details are removed

Infrastructure Validation

The init script performs comprehensive validation before deploying:

  • Checks for existing ACM certificates in the appropriate regions
  • Verifies DNS provider access (Route53 for AWS-managed domains, GoDaddy API for burialsatseasandiego.com)
  • Validates S3 bucket naming (all tech blog buckets follow the pattern {property}-tech)
  • Confirms CloudFront distributions are created and DNS propagates correctly

The dry-run mode allows verification of all planned changes before committing to AWS or DNS providers.

Handling Image & Content Corrections

As part of this session, we identified that burialsatseasandiego.sailjada.com had incorrect images for the "Imagine" and "Small Catamaran" sections. The generator logs this work: file updates to the HTML and image asset references are captured in the technical post, along with a progress board task created to track fleet image fixes and ensure consistent branding across all properties.

What's Next

The system is now operational across all four properties. Upcoming enhancements include:

  • Google Analytics audit and recommendations to increase bookings (separate engagement)
  • Automated image validation to catch broken references before deployment
  • Email template validation framework (email_template_validator.py is ready for expansion)
  • Unsubscribe monitoring dashboard integration (jada_unsubscribe_monitor.py foundation in place)

Each session's work will now be automatically documented, providing Sergio and other stakeholders with complete visibility into engineering