Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

Building Automated Technical Blog Infrastructure Across Four Sailing Operations Sites

This session involved architecting and deploying a comprehensive automated technical documentation system across four separate domain properties: queenofsandiego.com, sailjada.com, dangerouscentaur.com, and burialsatseasandiego.com. The goal was to create real-time, granular technical blog posts that capture infrastructure changes, deployment activities, and code modifications as they happen during development sessions.

What Was Done

Created a complete end-to-end system for automatic technical blog generation:

  • Built Python-based blog generator that parses Claude Code session transcripts (JSONL format)
  • Created infrastructure initialization script to provision S3 buckets, CloudFront distributions, and DNS records
  • Integrated Claude Code Stop hook to trigger blog post generation on session end
  • Added technical blog navigation links to Ship's Papers menus on all four sites
  • Configured four separate tech blog subdomains with appropriate SSL/TLS certificates
  • Implemented credential filtering to ensure no secrets appear in published posts

Technical Architecture

Session Transcript Parsing

The system reads Claude Code session transcripts stored in ~/.claude/projects/ in JSONL format. Each session contains timestamped entries for:

  • File operations (creates, edits, deletes) with full paths
  • Tool use events (AWS CLI, shell commands, Python scripts)
  • User interactions and requests

The blog generator (/Users/cb/Documents/repos/tools/tech_blog_generator.py) extracts relevant technical information from these transcripts, filters sensitive data, and generates formatted HTML blog posts. Each post includes:

  • Specific file paths modified (e.g., /Users/cb/Documents/repos/tools/jada_blast.py)
  • Infrastructure changes with exact AWS resource identifiers
  • Commands executed (with credentials redacted)
  • Decision rationale and architecture patterns

Infrastructure Provisioning

Created tech_blog_init.py to automate the provisioning of four parallel technical blog deployments. For each domain, the script:

  • Creates dedicated S3 bucket (e.g., qos-tech-blog, jada-tech-blog, dc-tech-blog, bats-tech-blog)
  • Configures bucket as website endpoint with index.html routing
  • Provisions CloudFront distribution pointing to S3 origin
  • Manages DNS records for subdomain routing (tech.queenofsandiego.com, tech.sailjada.com, etc.)
  • Handles ACM certificate validation across multiple DNS providers (Route53, Namecheap, GoDaddy)

The script intelligently handles certificate reuse where wildcard certs already exist. For example:

  • queenofsandiego.com uses existing wildcard cert *.queenofsandiego.com
  • sailjada.com uses existing wildcard cert *.sailjada.com
  • dangerouscentaur.com leverages existing CloudFront distribution on dc-sites bucket with wildcard cert
  • burialsatseasandiego.com required new ACM cert with GoDaddy DNS validation (using provided API credentials)

DNS and CDN Configuration

Different domains use different DNS providers, requiring provider-specific implementations:

  • Route53 (queenofsandiego.com, sailjada.com): Created alias records pointing to CloudFront distributions
  • Namecheap (dangerouscentaur.com): Created CNAME record for tech subdomain pointing to CloudFront distribution
  • GoDaddy (burialsatseasandiego.com): Added ACM DNS validation CNAME and technical blog CNAME via GoDaddy API

All CloudFront distributions use standard TLS configuration with HTTP-to-HTTPS redirects and gzip compression enabled for HTML/CSS/JS assets.

Integration Points

Claude Code Stop Hook

Registered a stop hook at ~/.claude/hooks/tech_blog_stop.sh in Claude Code settings. When a development session ends, this hook:

  • Extracts the current session transcript from Claude Code
  • Runs tech_blog_generator.py with the transcript as input
  • Uploads the generated HTML post to the appropriate tech blog S3 bucket
  • Invalidates the CloudFront distribution cache
  • Logs results to ~/.claude/logs/tech_blog_generation.log

Navigation Integration

Updated Ship's Papers navigation menus across all four site's index.html files to include new technical blog links. The menu structure adds technical documentation as a first-class navigation item visible to stakeholders like Sergio who want detailed transparency into ongoing work.

Credential and Security Handling

The system implements multiple layers of credential filtering:

  • Session parser strips AWS access keys, tokens, and secret identifiers
  • Command examples in posts show invocations but redact actual credentials
  • Sensitive file paths (like /Users/cb/.claude/ config files) are abbreviated or omitted
  • Email addresses and personal identifiers are redacted from captured data
  • Git commits and repository references use public-safe formats only

A credentials database (reference_godaddy_credentials.md) exists separately in project memory but is never accessed by the blog generator—the generator only receives pre-approved credentials for DNS operations via environment variables.

Key Decisions

Why Automated Rather Than Manual: Automated generation ensures posts are created immediately after work completes while details are fresh and exact. Manual blogging would be delayed and prone to imprecision. The granularity requirement (getting "into the weeds") demands exact file paths and command details that are only reliably captured programmatically.

Why Session-Based Rather Than Git-Based: Git commits only capture code changes, not infrastructure work, configuration changes, or the reasoning behind decisions. Session transcripts capture the complete context of what was done and why.

Why Four Separate Tech Blogs Rather Than One Aggregated: Each property operates independently with different stakeholders. Sergio cares specifically about queenofsandiego.com work. A unified blog would dilute relevance and require filtering. Separate blogs let each stakeholder focus on their property's technical evolution.

Why Route53/Namecheap/GoDaddy Mixed Approach: These domains were already registered and managed at different providers before this project. Rather than consolidate DNS (which would create migration risk), the system adapts to each provider's API capabilities.

Deployment Status

All four technical blogs are now live:

  • tech.queenofsandiego.com — S3 bucket qos-tech-blog, CloudFront D[distribution-id]