Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

Building Auto-Generated Technical Blog Infrastructure for Four Production Websites

What Was Done

Implemented a comprehensive automated technical documentation system that captures development work across four production websites and generates granular blog posts in real-time. The system creates parallel tech blog instances at tech.queenofsandiego.com, tech.sailjada.com, tech.dangerouscentaur.com, and tech.burialsatseasandiego.com, with each post exposing detailed infrastructure changes, file modifications, and command execution history.

Architecture Overview

The solution consists of three core components:

  • Claude Code Stop Hook (/Users/cb/.claude/hooks/tech_blog_stop.sh): Executes when development sessions end, capturing session transcripts and triggering blog generation
  • Blog Generator (/Users/cb/Documents/repos/tools/tech_blog_generator.py): Parses session JSONL transcripts and converts development artifacts into structured HTML blog posts
  • Infrastructure Init (/Users/cb/Documents/repos/tools/tech_blog_init.py): Provisions S3 buckets, CloudFront distributions, and DNS records for each tech blog subdomain

Infrastructure Provisioning

The system creates isolated infrastructure for each tech blog following this pattern:

  • S3 Buckets: Dedicated private buckets for each blog (e.g., qos-tech-blog, jada-tech-blog, dc-sites wildcard, bats-tech-blog)
  • CloudFront Distributions: Leveraged existing wildcard ACM certificates (*.queenofsandiego.com and *.sailjada.com) for rapid deployment. For dangerouscentaur, utilized existing wildcard distribution E2Q4UU71SRNTMB on dc-sites bucket. For burialsatseasandiego.com (GoDaddy-hosted), provisioned new ACM certificate with DNS validation
  • DNS Records: Route53 CNAME records for queenofsandiego.com and sailjada.com domains; Namecheap CNAME for dangerouscentaur; GoDaddy CNAME for burialsatseasandiego.com

Session Transcript Processing

The blog generator parses Claude Code session transcripts stored in JSONL format. Each session file contains structured entries for:

  • File modifications with exact paths (e.g., /Users/cb/Documents/repos/sites/queenofsandiego.com/index.html)
  • Commands executed with full argument lists
  • Tool invocations and results
  • Timestamp information for chronological ordering

The generator extracts relevant entries, filters out sensitive information (credentials, tokens, API keys), and organizes them by domain context. For example, modifications to queenofsandiego.com files trigger a post to tech.queenofsandiego.com.

Technical Details: Session Analysis

Sample transcript entries follow JSONL format with this structure:

{"type": "tool_use", "name": "read_file", "input": {"path": "/path/to/file"}, "output": "..."}
{"type": "command", "command": "aws s3 sync ...", "exit_code": 0}
{"type": "message", "role": "user", "content": "..."}

The generator processes these entries to build the blog post narrative, extracting:

  • File modifications: Exact paths and operation type (Write/Edit)
  • AWS operations: S3 uploads, CloudFront invalidations, Route53 changes
  • Command execution: Exact command syntax (with secrets redacted) and outcomes
  • Infrastructure changes: Resource creation, distribution updates, DNS propagation

Domain-Specific Routing

The system maps development work to appropriate tech blogs based on file paths and infrastructure targets:

  • Modifications to /repos/sites/queenofsandiego.com/ and related CloudFront distributions → tech.queenofsandiego.com
  • Modifications to /repos/sites/sailjada.com/ and Jada infrastructure → tech.sailjada.com
  • Dangerouscentaur site changes and dc-sites bucket updates → tech.dangerouscentaur.com
  • Burialsatseasandiego.com modifications and GoDaddy DNS work → tech.burialsatseasandiego.com

Secret Redaction

Before generating blog posts, the system filters transcripts to remove:

  • AWS credentials and profile information
  • ACM certificate validation records and DNS values
  • GoDaddy API credentials
  • CloudFront distribution IDs (where they might expose sensitive configs)
  • S3 bucket contents that contain personal data
  • Email addresses and contact information (except in appropriate context)

Only structural information and non-sensitive identifiers are included in published posts.

Navigation Integration

Tech blog links are added to the "Ship's Papers" menu in each website's navigation. The menu structure in index.html was updated to include:

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

This makes development transparency visible to stakeholders like Sergio without exposing credential or sensitive architectural details.

Certificate Management

The infrastructure init script intelligently handles certificates:

  • Wildcard certificates (queenofsandiego.com, sailjada.com): Existing ACM certificates reused, no additional validation required
  • Dangerouscentaur: Existing CloudFront wildcard distribution reused to avoid cert issues
  • Burialsatseasandiego.com: New ACM certificate provisioned with DNS validation CNAME added to GoDaddy nameservers

Key Decisions

Real-time vs. Batch Processing: Stop hooks execute immediately after session completion, enabling same-day post publication rather than scheduled batch jobs. This provides stakeholders with current information.

Granular Documentation: Posts capture specific file paths, command syntax, and resource names rather than high-level summaries. This allows engineering teams to drill down into exactly what changed and why.

Domain-Aware Routing: Each website gets its own tech blog subdomain, reflecting separate business contexts. Infrastructure remains isolated, preventing cross-domain information leakage.

Existing Infrastructure Leverage: Rather than provisioning new certificates for dangerouscentaur, the system reused the existing wildcard distribution. This reduces complexity and deployment time.

What's Next

  • Monitor burialsatseasandiego.com ACM certificate DNS validation and CloudFront distribution