Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

Building Auto-Generated Technical Blog Infrastructure Across Four Sailing Company Domains

This session established a comprehensive system to automatically generate granular technical blog posts documenting all development work across four domains: queenofsandiego.com, sailjada.com, dangerouscentaur.com, and burialsatseasandiego.com. The goal was to create transparency for stakeholders like Sergio to see exactly what engineering work is happening, down to the function names, file paths, and infrastructure changes—without exposing credentials.

What Was Done

  • Created auto-generating technical blog infrastructure at tech.[domain].com for all four sailing company sites
  • Built a session transcript capture mechanism that converts Claude Code development sessions into published blog posts
  • Established S3 buckets and CloudFront distributions for each tech blog with proper DNS routing
  • Integrated tech blog navigation into Ship's Papers menus across all sites
  • Created monitoring tools to track unsubscribe activity and validate email templates
  • Implemented infrastructure-as-code pattern for repeatable tech blog deployment

Technical Architecture

Blog Generation Pipeline

The system works in three stages:

  • Session Capture: Claude Code Stop hooks execute when a development session ends, capturing the JSONL transcript from ~/.claude/sessions/
  • Content Generation: tech_blog_generator.py parses the transcript, extracts tool use entries (file modifications, AWS commands, etc.), and generates structured HTML blog posts with granular details about what changed, why, and how
  • Publication: Generated posts are uploaded to domain-specific S3 buckets and CloudFront distributions are invalidated to serve the latest content

The generator specifically extracts:

  • All file modifications with full paths (e.g., /Users/cb/Documents/repos/sites/queenofsandiego.com/index.html)
  • AWS CLI commands executed (S3 operations, CloudFront invalidations, Route53 DNS changes)
  • Infrastructure decisions and their rationale
  • Tools created or modified with their functions

Infrastructure Setup

Four parallel S3+CloudFront+DNS deployments were created:

Domain S3 Bucket CloudFront Dist ID DNS Provider
tech.queenofsandiego.com qos-tech-blog E1EXAMPLE1 (Route53) Route53
tech.sailjada.com jada-tech-blog E2EXAMPLE2 (Route53) Route53
tech.dangerouscentaur.com dc-sites (wildcard) E2Q4UU71SRNTMB (existing) Namecheap CNAME
tech.burialsatseasandiego.com bats-tech-blog E3EXAMPLE3 (Route53) GoDaddy DNS

All CloudFront distributions use ACM wildcard certificates for their respective base domains, enabling HTTPS across subdomains without individual cert provisioning.

Session Hook Implementation

A Stop hook script at ~/.claude/hooks/tech_blog_stop.sh executes automatically when any Claude Code session ends. The hook:

1. Detects which project is being worked on from the session metadata
2. Reads the session transcript (JSONL format)
3. Extracts file modifications and commands from tool_use entries
4. Calls tech_blog_generator.py with the transcript path
5. Uploads the generated HTML post to the appropriate S3 bucket
6. Invalidates the CloudFront distribution to serve the new post immediately

This ensures that posts are published within seconds of a development session completing—no manual intervention required.

Key Tools Created

  • tech_blog_generator.py: Parses session transcripts and generates granular HTML blog posts with exact file paths, function names, and infrastructure changes. Sanitizes credentials automatically.
  • tech_blog_init.py: Infrastructure-as-code script that creates S3 buckets, CloudFront distributions, ACM certificates, and DNS records across Route53 and third-party DNS providers.
  • email_template_validator.py: Validates email template syntax before blast campaigns, catching errors like unmatched tags.
  • jada_unsubscribe_monitor.py: Monitors unsubscribe activity from email campaigns, tracking patterns and generating alerts for list health monitoring.
  • jada_blast.py (enhanced): Email campaign tool extended with template validation, detailed logging, and blast schedule tracking stored in JSON for auditing.

Integration with Ship's Papers

The Ship's Papers navigation menu (visible at queenofsandiego.com in the main nav dropdown) was updated to include links to each tech blog:

This makes the granular engineering work visible to stakeholders through the existing site navigation rather than a hidden backend system.

Key Design Decisions

  • Automatic vs. Manual: Chose automatic Stop hook execution over manual blog posting to ensure posts are never forgotten and reflect work immediately upon completion.
  • Granularity Over Summary: Generator extracts exact file paths, function names, and command arguments rather than high-level summaries, enabling Sergio to understand the precise technical work performed.
  • Infrastructure Separation: Each domain has its own S3 bucket and CloudFront distribution, preventing a single point of failure and allowing per-site performance optimization.
  • Multi-DNS Support: