Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

Automated Technical Blog Pipeline: Building Real-Time Development Documentation Across Four Sailing Operations

What Was Done

This session implemented a comprehensive automated blog generation system that captures granular technical work across four distinct domains: tech.queenofsandiego.com, tech.sailjada.com, tech.dangerouscentaur.com, and tech.burialsatseasandiego.com. The system automatically generates detailed technical blog posts from Claude Code session transcripts immediately upon session completion, ensuring real-time documentation of infrastructure changes, code modifications, and system updates.

The motivation was clear: stakeholders like Sergio need visibility into the technical decisions and implementation details—not high-level summaries. This blog pipeline provides forensic-level documentation of what changed, why, and how.

Technical Architecture

Core Components

  • Hook System: A Claude Code stop hook (/Users/cb/.claude/hooks/tech_blog_stop.sh) triggers automatically when development sessions end, capturing the session transcript before it's archived.
  • Blog Generator: Python script tech_blog_generator.py parses JSONL-formatted session transcripts, extracts file modifications and command execution details, and generates structured HTML blog posts.
  • Infrastructure Init: Python script tech_blog_init.py provisions S3 buckets, CloudFront distributions, and DNS records for each blog domain with proper ACM certificate validation.
  • Integration Layer: Updated navigation across all four sites to expose tech blogs via "Ship's Papers" menu dropdowns.

Data Flow

When a Claude Code session ends:

  1. The stop hook reads the session transcript from ~/.claude/sessions/ (JSONL format)
  2. tech_blog_generator.py parses tool use entries to extract: file paths modified, command invocations, AWS operations, DNS changes, and infrastructure provisioning
  3. The generator filters sensitive data (credentials, API keys, tokens) and formats output as structured HTML
  4. Generated post uploads to the appropriate S3 bucket: qos-tech-blog, jada-tech-blog, dc-tech-blog, or bats-tech-blog
  5. CloudFront cache invalidation ensures immediate visibility
  6. Blog index updates automatically

Infrastructure Provisioning

Domain-Specific Setup

Queen of San Diego (tech.queenofsandiego.com):

  • S3 bucket: qos-tech-blog (us-west-1)
  • CloudFront distribution: Origin points to S3 bucket
  • DNS: CNAME record via Route53 (existing *.queenofsandiego.com wildcard cert in ACM)
  • ACM certificate: Reused existing wildcard cert for *.queenofsandiego.com

Sail Jada (tech.sailjada.com):

  • S3 bucket: jada-tech-blog (us-east-1)
  • CloudFront distribution: Standard web distribution
  • DNS: Route53 CNAME
  • ACM certificate: Existing *.sailjada.com wildcard

Dangerous Centaur (tech.dangerouscentaur.com):

  • S3 bucket: dc-tech-blog
  • CloudFront distribution: Added origin to existing wildcard distribution (ID: E2Q4UU71SRNTMB) on dc-sites bucket
  • DNS: Namecheap CNAME pointing to CloudFront edge
  • Wildcard ACM cert already present

Burials at Sea San Diego (tech.burialsatseasandiego.com):

  • S3 bucket: bats-tech-blog
  • CloudFront distribution: New distribution created
  • DNS: GoDaddy CNAME via programmatic API (credentials validated against existing account)
  • ACM certificate: Requested new cert with DNS validation, CNAME record added via GoDaddy API

Key Infrastructure Decisions

  • Wildcard Certificate Reuse: Leveraged existing *.queenofsandiego.com and *.sailjada.com wildcard certs in ACM to avoid cert proliferation. This reduced provisioning time and certificate management overhead.
  • Regional Bucket Placement: QOS bucket in us-west-1 (closest to operations), Jada in us-east-1 (CloudFront origin optimization), others follow existing patterns.
  • DNS Provider Consistency: Route53 for queenofsandiego.com and sailjada.com; Namecheap for dangerouscentaur (existing setup); GoDaddy for burialsatseasandiego (programmatic API integration).
  • CloudFront Origin Configuration: S3 origin with OAC (Origin Access Control) instead of legacy OAI, restricting direct S3 access and forcing all traffic through CloudFront for proper caching and security headers.

Session Transcript Parsing Strategy

The generator parses JSONL session transcripts to extract three categories of technical detail:

Files Modified/Created:
  - Exact path: /Users/cb/Documents/repos/tools/tech_blog_generator.py
  - Action: Write (new file creation vs. edit)
  
Commands Executed:
  - Full command: "aws s3api create-bucket ..."
  - Tool: AWS CLI, Python, curl, etc.
  - Purpose: Infrastructure provisioning, testing, validation
  
Tool Invocations:
  - Function: upload_file() via boto3
  - Parameters: bucket name, key, content
  - AWS service: S3, CloudFront, Route53, etc.

Sensitive data filtering removes: API credentials, authentication tokens, password strings, AWS secret keys, and personally identifiable information before HTML generation.

Navigation Integration

Updated index.html on each site to expose tech blogs via dropdown menu under "Ship's Papers":

<li class="dropdown">
  <a href="#" class="dropdown-toggle">Ship's Papers</a>
  <ul class="dropdown-menu">
    <li><a href="/tools/shipcaptaincrew/">Ship/Captain/Crew Tool</a></li>
    <li><a href="https://tech.queenofsandiego.com">Technical Blog</a></li>
  </ul>
</li>