Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

Building a Granular Technical Blog System: Auto-Generated Documentation for Multi-Site Operations

Overview

This session focused on creating an automated technical documentation system that captures engineering work across four distinct maritime/hospitality websites in real-time. Instead of relying on manual summaries or high-level reviews, the system generates granular, detailed blog posts immediately after development sessions conclude, providing transparency into every infrastructure change, code modification, and deployment decision.

The Problem We Solved

Managing multiple Squarespace-integrated websites with custom tooling requires stakeholders like Sergio to understand not just what was built, but how and why. Manual documentation falls behind development velocity. The solution: automatic extraction of session activity into technical narratives published to dedicated tech blogs at:

  • tech.queenofsandiego.com
  • tech.sailjada.com
  • tech.dangerouscentaur.com
  • tech.burialsatseasandiego.com

Technical Architecture

Blog Infrastructure

Each tech blog runs on a dedicated S3 bucket + CloudFront distribution + Route53 DNS configuration:

  • S3 Buckets: qos-tech-blog, jada-tech-blog, dc-sites (wildcard), bats-tech-blog
  • CloudFront Distributions: Each bucket has a dedicated distribution with index.html default root object and error page routing
  • ACM Certificates: Wildcard certs for *.queenofsandiego.com and *.sailjada.com (both in us-east-1); individual cert for burialsatseasandiego.com
  • DNS Providers: Route53 for queenofsandiego.com and sailjada.com; Namecheap for dangerouscentaur.com; GoDaddy for burialsatseasandiego.com

Generation Pipeline

The system uses Claude Code's session hooks to intercept development sessions:

  • Hook Location: /Users/cb/.claude/hooks/tech_blog_stop.sh (executed when a Claude Code session ends)
  • Session Data Source: JSONL transcript file from /Users/cb/.claude/projects/[project-id]/sessions/[session-id]/transcript.jsonl
  • Processing: tech_blog_generator.py parses the transcript, extracts tool use entries (file writes, AWS CLI commands, etc.), and generates HTML articles
  • Infrastructure Init: tech_blog_init.py creates S3 buckets, CloudFront distributions, ACM certificates, and DNS records

Key Implementation Details

Session Hook Integration

The hook script captures the session ID and project context when Claude Code sessions terminate:

#!/bin/bash
# Triggered on session stop
TRANSCRIPT_FILE="$HOME/.claude/projects/[project-id]/sessions/[session-id]/transcript.jsonl"
python3 /Users/cb/Documents/repos/tools/tech_blog_generator.py \
  --transcript "$TRANSCRIPT_FILE" \
  --site-map queenofsandiego.com \
  --output-bucket qos-tech-blog

The script identifies which site(s) were affected based on file paths in the transcript, routes the generated post to the appropriate S3 bucket, and invalidates the CloudFront distribution cache.

Infrastructure as Code

Rather than manual AWS console clicks, tech_blog_init.py orchestrates:

  • S3 bucket creation with versioning and CORS policies for future integrations
  • CloudFront distribution configuration with proper origin, caching, and compression settings
  • ACM certificate requests (or wildcard certificate attachment for existing certs)
  • Route53 record creation or Namecheap/GoDaddy CNAME additions via API
  • Logging output to /tmp/tech_blog_infra.log for audit trail

Content Generation Strategy

The generator extracts granular detail by parsing transcript tool use entries:

  • File Operations: Exact file paths and modification types (Write vs. Edit)
  • AWS Commands: S3 uploads, CloudFront invalidations, Route53 updates (with credentials scrubbed)
  • Code Changes: Function names, variable assignments, logic modifications
  • Decision Context: Comments in MEMORY.md and project-specific handoff documents explain the "why"

Integration with Existing Sites

Navigation Updates

Each primary site (queenofsandiego.com, sailjada.com, dangerouscentaur.com, burialsatseasandiego.com) now includes a link to its tech blog in the Ship's Papers menu or equivalent navigation structure. For queenofsandiego.com, this appears as:

<a href="https://tech.queenofsandiego.com">Engineering Blog</a>

This makes technical documentation discoverable for stakeholders without breaking the public-facing site experience.

Security & Credential Handling

Critical safeguards prevent credential leaks:

  • Transcript parsing uses regex to identify and redact AWS access keys, API tokens, and passwords before processing
  • GoDaddy/Namecheap API calls use environment variables from repos.env (never hardcoded)
  • Generated HTML articles explicitly exclude credential references; only command structure and outcomes are documented
  • S3 buckets are not publicly writable; only CloudFront serves the tech blog content

Deployment Process

One-Time Setup

Run infrastructure initialization once per site:

python3 tech_blog_init.py \
  --site queenofsandiego.com \
  --aws-region us-east-1 \
  --dns-provider route53

The script outputs CloudFront domain names and ACM certificate validation records (if new certificates are required).

Continuous Generation

After each development session, the stop hook:

  1. Extracts the transcript JSONL file
  2. Identifies affected sites by analyzing file paths
  3. Generates HTML article with sanitized details
  4. Uploads to the appropriate tech blog S3 bucket
  5. Invalidates CloudFront cache with /* pattern to ensure immediate visibility
  6. Logs completion status to system logs

Why This Architecture

  • Automation: Eliminates manual blog writing; developers focus on building
  • Granularity: