Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

Implementing Automated Technical Blog Generation Across Four Sailing/Event Sites

This session established a fully automated technical documentation system that captures granular development work across four independent properties—queenofsandiego.com, sailjada.com, dangerouscentaur.com, and burialsatseasandiego.com—and publishes it in real-time to dedicated tech blogs. The goal was to create an audit trail detailed enough for stakeholders to understand exactly what engineering work is happening, down to specific file paths and infrastructure changes.

Architecture Overview

The system consists of three core components:

  • Session Capture Hook: A bash script that runs when Claude Code stops, capturing the development session transcript
  • Blog Generator: Python script that parses session data and extracts technical work with granular detail
  • Infrastructure Layer: S3 buckets, CloudFront distributions, and DNS routing for four independent tech blog sites

Each tech blog is independently hosted with its own CloudFront distribution and S3 bucket, allowing for isolation and independent scaling.

Infrastructure Setup

The infrastructure initialization script (/Users/cb/Documents/repos/tools/tech_blog_init.py) was built to handle deployment across multiple AWS accounts and DNS providers:

  • S3 Buckets Created:
    • tech-queenofsandiego-com (Route53 in queenofsandiego.com account)
    • tech-sailjada-com (Route53 in sailjada.com account)
    • dc-sites-techblogs (Namecheap DNS for dangerouscentaur)
    • tech-bats-com (GoDaddy DNS for burialsatseasandiego.com)
  • CloudFront Distributions: One per tech blog, leveraging existing wildcard ACM certificates where available (*.queenofsandiego.com, *.sailjada.com) to avoid certificate provisioning delays
  • DNS Routing:
    • Route53 ALIAS records for queenofsandiego and sailjada tech blogs
    • Namecheap CNAME record for dangerouscentaur (pointing to CloudFront distribution)
    • GoDaddy CNAME record for burialsatseasandiego.com (with ACM certificate validation through DNS)

Session Hook Implementation

The stop hook (/Users/cb/.claude/hooks/tech_blog_stop.sh) integrates with Claude Code's session lifecycle. When a development session ends, the hook:

  • Extracts the session transcript (JSONL format) from Claude's projects directory
  • Identifies all file modifications, tool invocations, and command executions
  • Passes structured session data to the blog generator
  • Logs activity to ~/.claude/logs/tech_blog_generator.log for debugging

The hook is registered in Claude Code settings (~/.claude/settings.json) under the hooks.stop configuration, ensuring it runs automatically without manual intervention.

Blog Generator Logic

The generator (/Users/cb/Documents/repos/tools/tech_blog_generator.py) parses session transcripts and extracts:

  • File Operations: Exact paths of created, modified, or deleted files with context about what changed
  • Infrastructure Changes: AWS resource names, CloudFront invalidations, DNS updates, S3 operations
  • Commands Executed: Shell commands run during the session (excluding credential exposure)
  • Tool Usage: Python tools invoked, their purpose, and their effects
  • Decision Rationale: Why specific technical choices were made

The generator filters sensitive data (credentials, API keys, tokens) before publishing. It generates HTML posts with proper semantic structure and publishes them to the appropriate S3 bucket via CloudFront invalidation to ensure cache busting.

Navigation Integration

Each site's Ship's Papers menu was updated to include a "Technical Development Blog" link:

  • queenofsandiego.com → Ship's Papers → Technical Development Blog (links to tech.queenofsandiego.com)
  • sailjada.com → Ship's Papers → Technical Development Blog (links to tech.sailjada.com)
  • dangerouscentaur.com → Ship's Papers → Technical Development Blog (links to tech.dangerouscentaur.com)
  • burialsatseasandiego.com → Ship's Papers → Technical Development Blog (links to tech.burialsatseasandiego.com)

Updates were made to the respective index.html files' navigation dropdowns to include these links in a maintainable, documented way.

Testing & Validation

The system was tested by processing the current session transcript through the blog generator. A sample post was uploaded to tech.queenofsandiego.com and verified to be:

  • Accessible via HTTPS at tech.queenofsandiego.com
  • Properly formatted with granular technical details
  • Free of credential exposure
  • CloudFront-cached for performance

CloudFront cache invalidation paths were configured to handle index.html updates immediately upon blog publication.

Key Technical Decisions

  • Independent Buckets & Distributions: Rather than consolidating all tech blogs into one resource, separate infrastructure per site allows for independent access controls, compliance isolation, and independent scaling if needed.
  • Automatic Invocation via Stop Hook: Triggering generation on session close (rather than polling) ensures minimal latency and zero manual steps for blog updates.
  • JSONL Transcript Parsing: Claude's native session transcripts are JSONL-formatted with rich metadata (tool use, file operations, etc.), making them ideal for automated extraction without additional instrumentation.
  • CloudFront Cache Invalidation: Posts are published immediately with /* invalidation to ensure readers see updates within seconds.
  • Multi-DNS Provider Support: The infrastructure script handles Route53 (AWS), Namecheap, and GoDaddy to accommodate existing domain configurations without consolidation.

What's Next

Future enhancements planned:

  • Integration with image asset uploads and CloudFront invalidation for documentation graphics
  • Tagging system to categorize posts by type (infrastructure, feature, bugfix, documentation)
  • RSS feed generation for each tech blog to allow stakeholder subscriptions
  • Automated link detection to cross-reference related posts across properties

The system is now live and will automatically publish a detailed post to the appropriate tech blog whenever a development session concludes.

```