Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

Building Automated Technical Blog Infrastructure Across Four Sailing & Event Sites

This session involved architecting and deploying an automated technical blog generation system across four separate domain properties: queenofsandiego.com, sailjada.com, dangerouscentaur.com, and burialsatseasandiego.com. The goal was to create a granular, session-based technical documentation system that captures infrastructure changes, code modifications, and deployment activities in real-time, with zero manual intervention required.

What Was Done

Created a complete infrastructure and automation layer consisting of:

  • Four new S3 buckets with static website hosting enabled (tech-qos-blog, tech-jada-blog, tech-dc-blog, tech-bats-blog)
  • Four CloudFront distributions with appropriate SSL/TLS certificates and cache invalidation support
  • DNS configuration across Route53 (sailjada.com, queenofsandiego.com) and GoDaddy (burialsatseasandiego.com)
  • Two Python automation scripts: tech_blog_generator.py and tech_blog_init.py
  • Claude Code Stop hook script (tech_blog_stop.sh) that runs on session completion
  • Integration into the Ship's Papers navigation menu on queenofsandiego.com and related properties
  • Session transcript parsing and analysis pipeline

Infrastructure Architecture

AWS Resources

Storage Layer: Four dedicated S3 buckets configured for static website hosting with block-public-access disabled to allow CloudFront access. Each bucket follows the naming convention tech-[domain-shorthand]-blog with index.html set as the default root object.

Distribution Layer: CloudFront distributions created for each property with the following characteristics:

  • Origin pointing to the corresponding S3 bucket's website endpoint (not the regular S3 endpoint)
  • Default root object set to index.html
  • Cache behavior configured to allow query strings and headers for dynamic content invalidation
  • SSL/TLS using existing wildcard certificates: *.queenofsandiego.com, *.sailjada.com, and *.dangerouscentaur.com
  • For burialsatseasadiego.com, ACM certificate requested with DNS validation via GoDaddy

DNS Configuration:

  • tech.queenofsandiego.com → Route53 CNAME to CloudFront distribution
  • tech.sailjada.com → Route53 CNAME to CloudFront distribution
  • tech.dangerouscentaur.com → Namecheap CNAME to CloudFront distribution (existing wildcard CF setup at dangerouscentaur)
  • tech.burialsatseasandiego.com → GoDaddy CNAME to CloudFront distribution with ACM certificate validation

Automation Pipeline

Stop Hook Mechanism

The system uses Claude Code's native Stop hook functionality. When a session ends, tech_blog_stop.sh is automatically invoked with the session transcript path as an argument. This script:

  • Receives the absolute path to the JSONL session transcript
  • Invokes tech_blog_generator.py with that transcript path
  • Captures generator output including generated HTML and S3 upload status
  • Logs all operations to /tmp/tech_blog_stop_[timestamp].log for debugging

The hook is registered in Claude Code's settings (~/.claude/settings.json) under the sessionStopHooks array, pointing to the executable script.

Session Transcript Parsing

Claude session transcripts are stored in JSONL format. The generator reads these line-by-line and extracts:

  • tool_use entries showing commands executed (with arguments, but no sensitive output)
  • File modification events (Write/Edit operations with full paths)
  • Timestamps for each operation
  • Assistant reasoning and technical decisions

The parser filters out:

  • Any content containing credential patterns (passwords, API keys, tokens, secrets)
  • Sensitive environment variables
  • AWS secret access keys and similar protected data
  • User feedback marked as sensitive in memory files

HTML Generation and Deployment

The generator produces valid HTML with:

  • Semantic structure using <h2>, <h3>, lists, and code blocks
  • Technical specificity: exact file paths, S3 bucket names, CloudFront distribution IDs, function names
  • Rationale for architectural decisions and design patterns
  • Command examples (with credentials redacted)
  • Proper linking between related posts

Generated posts are uploaded to the appropriate S3 bucket under a timestamped directory structure (e.g., posts/2025-01-14-session-123/index.html). After upload, the generator invokes CloudFront cache invalidation on the distribution's root path (/*) to ensure immediate visibility.

Navigation Integration

The Ship's Papers navigation menu on queenofsandiego.com was updated to include a "Technical Blog" link pointing to https://tech.queenofsandiego.com. This link appears in the main dropdown menu, making it discoverable for stakeholders like Sergio who want to see granular implementation details.

Each site's index.html was similarly updated with appropriate navigation structure, ensuring users can discover the technical documentation from the main properties.

Key Architectural Decisions

Why S3 + CloudFront instead of direct S3 hosting? CloudFront provides HTTPS/TLS termination, cache invalidation capabilities, and geographic distribution. It also allows us to use existing wildcard certificates across the domain portfolio without managing individual domain certificates.

Why parse session transcripts instead of hooking directly into the dev environment? Session transcripts provide a complete, immutable audit trail. They're already timestamped, include full context, and prevent us from missing work that happened earlier in a session. This approach also respects the natural Claude Code workflow without requiring environment setup.

Why separate blog infrastructure per domain? Each property has its own audience and governance model. Separating the blogs allows fine-grained access control, domain-specific branding, and independent cache management. The infrastructure is identical, so the pattern scales horizontally.

Why GoDaddy for burialsatseasandiego? That domain's DNS is already managed there. Rather than adding migration complexity, we provisioned an ACM certificate with DNS validation and added the CNAME through GoDaddy's API (using existing service credentials), avoiding manual DNS steps.

What's Next

  • Test the Stop hook on the next session completion and validate post generation
  • Fix image assets on burialsatseasandiego.com (