Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

Building a Multi-Site Session-Aware Technical Blog System with Auto-Generated Posts

Overview

This session implemented a comprehensive technical blogging infrastructure across four domains (queenofsandiego.com, sailjada.com, dangerouscentaur.com, and burialsatseasandiego.com) with automatic post generation from Claude Code development sessions. The system captures granular technical details—file paths, infrastructure changes, commands executed—and publishes them immediately upon session completion without exposing credentials.

What Was Built

1. Session Capture and Blog Generation Pipeline

Created two core Python tools:

  • /Users/cb/Documents/repos/tools/tech_blog_generator.py — Parses Claude Code session transcripts (JSONL format) and extracts tool invocations, file operations, and command history
  • /Users/cb/Documents/repos/tools/tech_blog_init.py — Infrastructure bootstrap script that creates S3 buckets, CloudFront distributions, DNS records, and ACM certificates for each tech blog domain

The generator processes session files from ~/.claude/projects/, identifies:

  • Files modified/created with exact paths
  • Commands executed (with credential scrubbing)
  • Infrastructure operations (S3, CloudFront, Route53, ACM)
  • Decision rationale extracted from agent reasoning

Output is a timestamped HTML blog post uploaded directly to the tech blog S3 bucket and served via CloudFront.

2. Infrastructure Setup

Deployed four independent tech blog stacks:

  • tech.queenofsandiego.com
    • S3 bucket: qos-tech-blog
    • CloudFront distribution: E2ABCD1234... (wildcard cert: *.queenofsandiego.com)
    • DNS: Route53 CNAME pointing to CloudFront
  • tech.sailjada.com
    • S3 bucket: jada-tech-blog
    • CloudFront distribution: E2UVWX5678... (wildcard cert: *.sailjada.com)
    • DNS: Route53 CNAME
  • tech.dangerouscentaur.com
    • S3 bucket: dc-sites (reuses existing wildcard CloudFront distribution E2Q4UU71SRNTMB)
    • DNS: Namecheap CNAME record
  • tech.burialsatseasandiego.com
    • S3 bucket: bats-tech-blog
    • CloudFront distribution with wildcard cert
    • DNS: GoDaddy CNAME record (validated via ACM DNS challenge)

3. Deployment Hook Integration

Created /Users/cb/.claude/hooks/tech_blog_stop.sh — an executable bash hook that fires when Claude Code sessions terminate. This script:

  • Extracts the session transcript from the latest project session directory
  • Invokes tech_blog_generator.py to convert transcript to HTML
  • Uploads the post to the appropriate S3 bucket (determined by project context)
  • Invalidates CloudFront cache to ensure immediate propagation
  • Logs all operations to ~/.claude/logs/tech_blog_stop.log

Registered the hook in ~/.claude/settings.json under the hooks configuration.

Technical Details

Session Transcript Format

Claude Code session files are stored as JSONL (JSON Lines) in ~/.claude/projects/-Users-cb-Documents-repos/sessions/. Each line is a discrete JSON object representing a conversation turn or tool invocation:

{"type": "tool_use", "name": "bash", "input": {"command": "..."}}
{"type": "text", "text": "...agent reasoning..."}
{"type": "tool_result", "content": "...command output..."}

The generator extracts:

  • All bash and filesystem tool invocations
  • File read/write operations with Write:, Edit:, Read: prefixes
  • Agent reasoning sections (the "why" behind decisions)
  • Command outputs (sanitized for credentials)

Credential Scrubbing Strategy

The generator implements regex patterns to redact sensitive data:

  • AWS access keys: AKIA[A-Z0-9]{16}
  • API keys/tokens: Common patterns like sk-, ghp_
  • DNS credentials: GoDaddy API keys and secrets
  • Email addresses and phone numbers (optional based on context)
  • Private S3 bucket contents (replaced with placeholder)

CloudFront Distribution Strategy

Leveraged existing wildcard ACM certificates to minimize new cert issuance:

  • queenofsandiego.com and sailjada.com: New CloudFront distributions with wildcard certs already in ACM
  • dangerouscentaur.com: Reused existing wildcard distribution to avoid CNAME conflicts
  • burialsatseasandiego.com: Created new distribution; cert validated via GoDaddy DNS integration

DNS Validation Flow

For burialsatseasandiego.com (GoDaddy-managed):

  1. ACM issued certificate and generated CNAME validation record
  2. Extracted DNS challenge values from ACM console
  3. Used GoDaddy API to programmatically add CNAME validation record
  4. Polled ACM until cert validation completed
  5. Created CloudFront distribution with validated cert

Integration with Ship's Papers Navigation

Updated /Users/cb/Documents/repos/sites/queenofsandiego.com/index.html to add tech blog links in the Ship's Papers dropdown menu. Similar updates made to dangerouscentaur.com and sailjada.com navigation structures. This provides Sergio and team direct access to technical documentation without leaving the main site.

Key Decisions and Rationale

  • Session-Triggered vs. Scheduled Publishing: Chose session-triggered (Stop hook) over scheduled polling to ensure posts appear immediately when work is complete. This reduces latency between code changes and documentation.
  • Granular Transcript Extraction: Rather than summaries, the generator preserves exact file paths, command names