Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

Building an Automated Technical Blog System Across Four Domains

This session focused on implementing an automated, session-aware technical blog generation system that captures development work granularly across four domains: tech.queenofsandiego.com, tech.dangerouscentaur.com, tech.sailjada.com, and tech.burialsatseasandiego.com. The goal was to create a transparent audit trail of all technical work—detailed enough that stakeholders can understand exactly what's being built and why.

System Architecture Overview

The solution consists of three primary components:

  • Session Capture Hook: A Claude Code stop hook that intercepts session transcripts and feeds them to the blog generator
  • Blog Generator: Python script that parses JSONL-formatted session transcripts, extracts technical work, redacts credentials, and generates HTML blog posts
  • Infrastructure: S3 buckets, CloudFront distributions, and DNS records for each tech blog domain

Infrastructure Setup

Each tech blog required independent AWS infrastructure:

  • S3 Buckets: Created private S3 buckets for each domain (qos-tech-blog, jada-tech-blog, dc-sites, bats-tech-blog) with versioning enabled
  • CloudFront Distributions: Configured distributions for qos, jada, and bats tech blogs with ACM wildcard certificates (*.queenofsandiego.com and *.sailjada.com)
  • DNS Configuration:
    • queenofsandiego.com and sailjada.com: Route53 CNAME records pointing to CloudFront distributions
    • dangerouscentaur.com: Leveraged existing wildcard CloudFront distribution (E2Q4UU71SRNTMB) on dc-sites bucket with Namecheap CNAME
    • burialsatseasandiego.com: GoDaddy DNS with Route53 nameservers configured; added ACM validation CNAME via GoDaddy API

Session Transcript Processing

The core challenge was extracting meaningful technical content from Claude Code session transcripts. Session files are stored as JSONL (JSON Lines) format in ~/.claude/projects/ with the following structure:

{"type": "user_message", "content": "..."}
{"type": "assistant_message", "content": "..."}
{"type": "tool_use", "name": "bash", "input": {"command": "..."}}
{"type": "tool_result", "content": "..."}

The blog generator reads these transcripts and extracts:

  • File modifications (Write/Edit operations with exact paths)
  • Commands executed (bash, file operations, AWS CLI calls)
  • Tool usage patterns and infrastructure changes
  • Decision rationale from assistant messages

Credential Redaction Strategy

The system implements layered credential protection:

  • Automatic Pattern Matching: Regex patterns identify and redact AWS access keys, API tokens, email addresses, and common credential formats
  • Environment Variable Filtering: Strips values from output when env var names suggest secrets (API_KEY, PASSWORD, CREDENTIAL, etc.)
  • Manual Redaction Tags: Developers can wrap sensitive content with <redacted> tags for additional safety
  • Safe Command Display: Shows command structure without sensitive arguments (e.g., aws s3 cp [redacted].html s3://[redacted]/)

Blog Post Generation and Publishing

The workflow:

  1. Claude Code stop hook triggers /Users/cb/.claude/hooks/tech_blog_stop.sh
  2. Hook extracts session transcript path and calls tech_blog_generator.py
  3. Generator parses transcript, creates structured HTML article
  4. Article is uploaded to the domain-specific S3 bucket with path s3://[bucket]/posts/YYYY/MM/DD/[slug].html
  5. CloudFront distribution is invalidated to clear cache
  6. Index page is regenerated with updated post listings

Articles include metadata (timestamp, word count, file paths touched, AWS resources modified) in a structured header for easy parsing and filtering.

Integration with Ship's Papers Navigation

Each main site (queenofsandiego.com, sailjada.com, dangerouscentaur.com, burialsatseasandiego.com) now includes a "Technical Blog" link in the Ship's Papers dropdown menu, pointing to the respective tech subdomain. This provides transparency to stakeholders—particularly Sergio—about ongoing technical work without requiring direct access to development tools.

Configuration Management

Infrastructure configuration is persisted in /Users/cb/.claude/projects/-Users-cb-Documents-repos/memory/project_tech_blogs.md with the following details:

  • Domain-to-S3-bucket mappings
  • CloudFront distribution IDs
  • Route53 zone IDs
  • DNS provider details (Route53 vs. Namecheap vs. GoDaddy)
  • ACM certificate ARNs
  • Blog generator settings (post format, archive structure, redaction rules)

Key Decisions and Trade-offs

Why Static Site Generation: Avoiding a dynamic backend eliminates database requirements, reduces operational complexity, and ensures the tech blogs are always available even if the primary sites are down.

Why JSONL Session Format: Claude Code stores transcripts in JSONL to support streaming and incremental parsing. This allows the generator to process large sessions without loading entire transcripts into memory.

Why Domain-Specific Buckets: Separate S3 buckets per domain allow granular access control, billing tracking, and future expansion (e.g., static assets, downloadable reports).

Why CloudFront Caching: CDN distribution reduces origin latency, handles traffic spikes, and provides DDoS protection. Cache invalidation on new posts ensures readers see latest content within seconds.

What's Next

The system is now live and will auto-generate posts on subsequent Claude Code sessions. Next priorities include:

  • Adding full-text search and tag-based filtering to tech blog indices
  • Implementing RSS/Atom feed generation for each tech domain
  • Setting up CloudWatch alarms on CloudFront error rates and S3 access logs
  • Creating a weekly digest post summarizing all technical changes
  • Integrating Google Analytics 4 tracking to monitor stakeholder engagement with tech blogs

This creates a persistent, detailed audit trail of all technical work—ideal for demonstrating progress, onboarding new team members, and maintaining institutional knowledge.

```