Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

Building an Automated Technical Documentation System for Four Domain Properties

This session implemented a comprehensive automated technical blog generation system across four separate domain properties: queenofsandiego.com, sailjada.com, dangerouscentaur.com, and burialsatseasandiego.com. The system captures granular development work in real-time and publishes it to dedicated tech.[domain].com subdomains, making technical decisions and infrastructure changes fully transparent to stakeholders.

Problem Statement

Previously, technical work across multiple properties had no centralized documentation. Without visibility into the granular details of infrastructure changes, deployments, and code modifications, stakeholders couldn't audit what was being done or understand the engineering decisions behind changes. The goal was to create a system that:

  • Automatically captures session work across all domains
  • Generates granular, detailed technical posts (not high-level summaries)
  • Makes posts immediately available after session completion
  • Integrates seamlessly into existing site navigation
  • Maintains security by scrubbing all credentials and sensitive data

Architecture Overview

The solution consists of three primary components:

  • Session Capture Hook: Claude Code integration that runs when sessions end
  • Blog Generator: Python script that parses session transcripts and generates HTML posts
  • Infrastructure Layer: S3 buckets, CloudFront distributions, and DNS records for each tech blog

Infrastructure Setup

Each domain received dedicated infrastructure:

queenofsandiego.com Tech Blog

  • S3 bucket: tech-queenofsandiego-com
  • CloudFront distribution: Uses existing *.queenofsandiego.com wildcard ACM certificate
  • DNS: Route53 hosted zone for queenofsandiego.com with CNAME to CloudFront
  • Endpoint: tech.queenofsandiego.com

sailjada.com Tech Blog

  • S3 bucket: tech-sailjada-com
  • CloudFront distribution: Uses existing *.sailjada.com wildcard ACM certificate
  • DNS: Route53 hosted zone for sailjada.com with CNAME to CloudFront
  • Endpoint: tech.sailjada.com

dangerouscentaur.com Tech Blog

  • S3 bucket: dc-sites (shared wildcard distribution)
  • CloudFront distribution: Existing distribution E2Q4UU71SRNTMB with dc-sites S3 origin
  • DNS: Namecheap CNAME record (dangerouscentaur uses Namecheap DNS, not AWS Route53)
  • Endpoint: tech.dangerouscentaur.com

burialsatseasandiego.com Tech Blog

  • S3 bucket: tech-burialsatseasandiego-com
  • CloudFront distribution: New distribution with ACM wildcard certificate validation via GoDaddy DNS
  • DNS: GoDaddy (burialsatseasandiego.com is registered at GoDaddy, not AWS)
  • Endpoint: tech.burialsatseasandiego.com

All distributions use the same caching strategy: CloudFront forwards all headers to S3, with 300-second default TTL for index.html and 31536000-second cache for static assets (with versioning).

Python Blog Generator Implementation

The generator script (/Users/cb/Documents/repos/tools/tech_blog_generator.py) reads Claude Code session transcripts and transforms them into structured HTML blog posts:

# Core workflow:
1. Parse JSONL session transcript
2. Extract tool_use entries (file writes/edits, command executions)
3. Build domain-to-content mapping
4. Generate HTML post with:
   - Timestamp from session
   - List of modified files organized by domain
   - Commands executed with output
   - Navigation links to relevant site documentation
5. Scrub all credentials, API keys, and secrets
6. Upload to appropriate S3 bucket
7. Invalidate CloudFront distribution cache

Key security features in the generator:

  • Redacts patterns matching AWS credentials, API keys, and tokens
  • Filters out sensitive environment variables
  • Excludes credential files and secrets from file listings
  • Strips password/token fields from command output

Claude Code Integration

A Stop hook script (/Users/cb/.claude/hooks/tech_blog_stop.sh) runs automatically when a Claude Code session ends:

#!/bin/bash
# Runs after each Claude Code session completes
# Extracts the session transcript
# Calls the blog generator
# Handles errors and logging

The hook is configured in Claude Code settings (/Users/cb/.claude/settings.json) to execute on session termination, creating a fully automated publishing pipeline.

Navigation Integration

The Ship's Papers menu system across all properties now includes a "Technical Blog" link pointing to the respective tech.[domain].com subdomain. This was added to:

  • queenofsandiego.com/index.html navigation menu
  • Navigation will be updated similarly on other properties

This ensures stakeholders like Sergio can easily access detailed technical documentation directly from the main site.

Post-Session Image Fix and Task Management

During infrastructure setup, incorrect imagery was identified on burialsatseasandiego.sailjada.com (displaying generic catamaran images instead of fleet-specific images). Two actions were taken:

  • Updated /burialsatseasandiego/notes/email_gipsy_kings_2026.html with correct image references
  • Updated /burialsatseasandiego/notes/email_birthday_sail_2026.html with fleet-specific imagery
  • Created progress board card tracking remaining "fleet image fixes" as a needs-you task

Email Template Validation

Created email_template_validator.py to ensure HTML email templates meet baseline requirements:

  • Validates required email salutation styles
  • Checks for minimum group size declarations (minimum 10 guests threshold)
  • Ensures template consistency across blast campaigns

This was integrated into the jada_blast.py email campaign system to prevent invalid templates from being sent.

Unsubscribe Monitoring

Created jada_unsubscribe_monitor.py to track email unsubscribe patterns across the sailjada.com mailing list:

  • Monitors blast schedule definitions in notes/blast_schedule.json
  • Identifies unsubscribe trends that might indicate content or timing