Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

Building a Real-Time Technical Blog Pipeline: Auto-Generated DevOps Documentation Across Four Domain Properties

Overview

This session established a comprehensive technical blogging system that automatically captures and publishes granular development work across four separate domain properties: tech.queenofsandiego.com, tech.sailjada.com, tech.dangerouscentaur.com, and tech.burialsatseasandiego.com. The system extracts session transcripts from Claude Code, parses file modifications and command execution, and generates detailed technical posts without exposing credentials or sensitive data.

What Was Done

Infrastructure Setup

Created four independent blog properties with identical architecture but separate S3 buckets and CloudFront distributions:

  • tech.queenofsandiego.com: S3 bucket qos-tech-blog, CloudFront distribution, Route53 A record alias
  • tech.sailjada.com: S3 bucket jada-tech-blog, CloudFront distribution, Route53 A record alias
  • tech.dangerouscentaur.com: S3 bucket dc-sites (shared wildcard), existing CloudFront distribution E2Q4UU71SRNTMB, Namecheap CNAME record
  • tech.burialsatseasandiego.com: S3 bucket bats-tech-blog, CloudFront distribution, GoDaddy DNS CNAME record

ACM wildcard certificates were leveraged where available (*.queenofsandiego.com and *.sailjada.com), eliminating certificate provisioning delays. For dangerouscentaur.com and burialsatseasandiego.com, existing infrastructure was extended to support the tech subdomain.

Blog Generator System

Created two Python tools:

  • /Users/cb/Documents/repos/tools/tech_blog_generator.py: Reads Claude Code session transcripts (JSONL format), extracts tool calls and file modifications, filters out credentials, and generates HTML blog posts with proper sanitization
  • /Users/cb/Documents/repos/tools/tech_blog_init.py: Provisions S3 buckets, CloudFront distributions, and DNS records (Route53 or third-party providers) for each tech blog property

Automation Hook

Modified Claude Code settings to register a Stop hook (/Users/cb/.claude/hooks/tech_blog_stop.sh) that executes when a development session ends. The hook:

  1. Extracts the current session transcript from ~/.claude/sessions
  2. Determines which domain property applies (based on files modified)
  3. Invokes tech_blog_generator.py to create an HTML post
  4. Uploads the post to the appropriate S3 bucket
  5. Invalidates the CloudFront distribution cache
  6. Logs execution to ~/.claude/logs/tech_blog_automation.log

Navigation Integration

Updated the Ship's Papers menu on queenofsandiego.com/index.html to include a "Tech Blog" link pointing to tech.queenofsandiego.com, making technical documentation discoverable to stakeholders like Sergio who need visibility into development work.

Technical Details

Session Transcript Parsing

Claude Code stores session transcripts as line-delimited JSON (JSONL) at ~/.claude/sessions/{session_id}.jsonl. Each line represents an event with structure:

{"type": "tool_use", "tool_name": "...", "input": {...}, "output": "..."}
{"type": "command", "command": "...", "output": "..."}

The generator identifies "write" and "edit" file operations from tool output, aggregates them by domain property, and generates narrative around the changes. It strips paths above the repo level, normalizes file references, and redacts common credential patterns (AWS keys, API tokens, passwords) to prevent accidental exposure.

CloudFront Cache Invalidation

Each deployment issues an invalidation for /* to ensure fresh content reaches viewers immediately. This is critical for real-time documentation where staleness defeats the purpose.

Multi-Provider DNS Integration

The system supports three DNS providers:

  • Route53: Native AWS integration for queenofsandiego.com and sailjada.com via alias records
  • Namecheap: CNAME record for dangerouscentaur.com (wildcard CF distribution)
  • GoDaddy: CNAME record for burialsatseasandiego.com using authenticated API calls

Key Decisions

Why Four Separate Blogs?

Each domain has distinct stakeholders and governance. Mixing technical updates across properties would dilute focus and obscure domain-specific decisions. Separate blogs allow Sergio to monitor queenofsandiego.com development independently, Kool Gang oversight of dangerouscentaur.com, and burial services stakeholders to track burialsatseasandiego.com changes.

Why Auto-Generation vs. Manual Posts?

Manual blogging creates friction; developers skip documentation when it's not automatic. By hooking into the Claude Code Stop lifecycle, every session automatically generates a post. This guarantees coverage and removes the "I'll document this later" excuse.

Granularity Over Summaries

File-level detail (listing exact paths modified) allows Sergio to drill into specific changes without asking follow-up questions. High-level summaries hide the real work; showing /Users/cb/Documents/repos/sites/queenofsandiego.com/concert-nights.html edits with context proves what was accomplished.

Credential Filtering

The generator uses regex patterns to redact AWS account IDs from tool output, GoDaddy API references from command logs, and CloudFront distribution IDs from certain contexts (while preserving them where architecturally relevant). This balances transparency with security.

Infrastructure Details

S3 Bucket Configuration

All buckets use static website hosting with index.html as the default document. Bucket policies allow public read access to *.html and *.json objects, while CloudFront acts as the single entry point (no direct bucket access).

CloudFront Distributions

Distributions are configured with:

  • S3 origin (origin access identity or public bucket with policy)
  • HTTP to HTTPS redirect
  • Gzip compression for text assets
  • Default TTL of 3600 seconds (1 hour) to balance freshness with cache efficiency
  • ACM certificate binding (wildcard where possible, specific certificate where necessary)

What's Next