Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

Building a Granular Technical Blog System Across Four Maritime Sites

This session implemented a fully automated technical blog infrastructure that captures development work in real-time across four distinct maritime domains: queenofsandiego.com, sailjada.com, dangerouscentaur.com, and burialsatseasandiego.com. The system generates detailed, engineering-focused posts that document infrastructure changes, code modifications, and feature deployments—designed for technical stakeholders like Sergio to audit exactly what's being built and why.

Architecture Overview

The system consists of three core components:

  • Tech Blog Generator (/Users/cb/Documents/repos/tools/tech_blog_generator.py): Parses Claude Code session transcripts in JSONL format and transforms them into detailed HTML articles
  • Infrastructure Initialization (/Users/cb/Documents/repos/tools/tech_blog_init.py): Provisions S3 buckets, CloudFront distributions, and DNS records for each tech blog subdomain
  • Session Capture Hook (/Users/cb/.claude/hooks/tech_blog_stop.sh): Executes at session end to automatically generate and deploy blog posts

Infrastructure Provisioning Details

Each tech blog required dedicated cloud resources. The infrastructure script handles this automatically:

  • S3 Buckets: Created versioned buckets with public read access for static HTML storage
    • tech-queenofsandiego-blog (primary domain)
    • tech-sailjada-blog
    • tech-dangerouscentaur-blog (reuses existing dc-sites bucket)
    • tech-burialsatseasandiego-blog
  • CloudFront Distributions: Configured with compression, caching policies, and error handling
    • queenofsandiego.com: Uses existing wildcard ACM cert (*.queenofsandiego.com)
    • sailjada.com: Uses existing wildcard ACM cert (*.sailjada.com)
    • dangerouscentaur.com: Routes through existing wildcard distribution (E2Q4UU71SRNTMB)
    • burialsatseasandiego.com: Provisioned new cert with GoDaddy DNS validation
  • DNS Configuration: Each subdomain points to its CloudFront origin
    • Route53-hosted zones (queenofsandiego.com, sailjada.com) receive ALIAS records
    • Namecheap-hosted dangerouscentaur.com receives CNAME records
    • GoDaddy-hosted burialsatseasandiego.com receives CNAME records for ACM validation and tech blog CNAME

Session Transcript Processing

The blog generator reads Claude Code session transcripts stored in /Users/cb/.claude/projects/-Users-cb-Documents-repos/sessions/. Each transcript is a JSONL file containing:

  • User messages and context
  • Tool use entries (file reads, writes, edits, command executions)
  • Timestamps and session metadata

The generator extracts granular details from tool use records:

  • File Operations: Exact paths of created/modified files with operation type (Write/Edit)
  • Commands Executed: AWS CLI, Python scripts, shell commands with sanitized arguments
  • Infrastructure Changes: S3 bucket names, CloudFront distribution IDs, Route53 hosted zone changes
  • Code Changes: Function modifications, configuration updates, script enhancements

This granularity means Sergio can see not just "updated email system" but rather "edited jada_blast.py lines 45-67 to add email_template_validator.py integration with three new validation functions: validate_salutation(), validate_link_structure(), validate_unsubscribe_footer()."

Navigation Integration

The Ship's Papers menu on each site now includes a "Technical Blog" link that appears in the main navigation dropdown. For queenofsandiego.com, this required:

  • Updating /Users/cb/Documents/repos/sites/queenofsandiego.com/index.html to add tech blog link in the Ship's Papers section
  • Maintaining consistent styling with existing navigation elements
  • Ensuring CloudFront cache invalidation after HTML updates

The same navigation pattern applies to the other three sites, with URLs updated to their respective tech subdomains.

Automated Post Generation Workflow

The session stop hook (invoked automatically when exiting Claude Code sessions) performs these steps:


1. Reads the session transcript JSONL file
2. Extracts tool use entries and command records
3. Determines which site(s) were modified based on file paths
4. Generates domain-specific HTML articles
5. Uploads articles to the appropriate S3 bucket
6. Invalidates CloudFront distribution caches
7. Logs generation results with timestamps

This ensures that within seconds of completing development work, detailed technical documentation is published and live at the corresponding tech blog subdomain.

Content Structure and Filtering

Generated posts follow a consistent technical format:

  • Title: Specific to the work performed (e.g., "Adding Email Template Validation and Unsubscribe Monitoring")
  • Summary Section: High-level overview of what changed and why
  • Technical Details: Line-by-line code changes, file paths, function names
  • Infrastructure Changes: S3 uploads, CloudFront invalidations, DNS updates with exact resource names
  • Key Decisions: Rationale behind architectural choices
  • Impact: What stakeholders can now do differently

The system sanitizes all output to remove credentials, API keys, tokens, and sensitive personal data while preserving technical accuracy.

Cross-Domain Considerations

Because multiple sites share infrastructure patterns, the system smartly deduplicates content. For example, when building this very blog system across all four domains, it generated a single comprehensive post for queenofsandiego.com's tech blog (the primary domain) and referenced that post in the other three tech blogs, avoiding redundant documentation while maintaining site-specific context.

What's Next

The system is now live and capturing all development work automatically. Future enhancements planned include:

  • RSS feed generation for each tech blog to enable subscription
  • Search indexing to allow Sergio to query specific changes across domains
  • Integration with monitoring systems to capture infrastructure alerts as tech blog posts
  • Automated image optimization and tagging for referenced files

The technical blog system transforms opacity into accountability—every code change, infrastructure modification, and configuration update is now immediately visible to stakeholders in a granular, searchable format designed for engineers who want to understand exactly what's been built and why.

```