Sail JADA — Engineering Log

Technical work on sailjada.com and the JADA booking systems

```html

Building a Granular Technical Blog System Across Four Sailing/Charter Properties

This session established an automated technical documentation system that captures development work in real-time across four distinct web properties: queenofsandiego.com, sailjada.com, dangerouscentaur.com, and burialsatseasandiego.com. Each property now has its own tech blog (tech.[domain].com) that automatically publishes detailed posts about infrastructure changes, code modifications, and deployment activities—giving stakeholders like Sergio complete visibility into ongoing work without exposing credentials.

Architecture Overview

The system consists of three primary components:

  • Blog Generator (/Users/cb/Documents/repos/tools/tech_blog_generator.py): Reads Claude session transcripts in JSONL format, extracts tool use and file modification events, filters out sensitive data, and generates HTML posts
  • Infrastructure Initializer (/Users/cb/Documents/repos/tools/tech_blog_init.py): Creates S3 buckets, CloudFront distributions, Route53 DNS records, and ACM certificates for each tech blog domain
  • Claude Code Hook (/Users/cb/.claude/hooks/tech_blog_stop.sh): Executes on session end, triggering blog generation and S3/CloudFront deployment

Infrastructure Setup: Domains and Distribution

Each property received identical infrastructure patterns but routed through different DNS providers based on existing domain setups:

  • tech.queenofsandiego.com: S3 bucket qos-tech-blog → CloudFront distribution (origin: qos-tech-blog.s3.us-west-2.amazonaws.com) → Route53 alias record (leveraging wildcard cert *.queenofsandiego.com)
  • tech.sailjada.com: S3 bucket jada-tech-blog → CloudFront distribution → Route53 alias record (using wildcard cert *.sailjada.com)
  • tech.dangerouscentaur.com: S3 bucket dc-tech-blog → Existing CloudFront wildcard distribution (E2Q4UU71SRNTMB, already serving dc-sites bucket) → Namecheap CNAME record pointing to CloudFront domain
  • tech.burialsatseasandiego.com: S3 bucket bats-tech-blog → CloudFront distribution → GoDaddy DNS CNAME record with ACM certificate validation

This mixed-provider approach (Route53 for AWS-native domains, Namecheap for dangerouscentaur, GoDaddy for burialsatseasandiego) reflects real-world domain registration patterns and required conditional logic in the infrastructure init script to detect and use existing credentials.

The Blog Generation Pipeline

When a Claude Code session ends, the stop hook executes this sequence:

1. Read session transcript from ~/.claude/sessions/[timestamp].jsonl
2. Extract all "tool_use" blocks and "write"/"edit" file operations
3. Filter out sensitive patterns:
   - AWS credentials and access keys
   - API tokens and secrets
   - Database passwords
   - Private email addresses
   - Phone numbers
   - Card/payment data
4. Normalize file paths (convert absolute paths to relative)
5. Group modifications by domain (queenofsandiego.com files → QOS blog, etc.)
6. Generate HTML post with:
   - Timestamp
   - Modified/created files list
   - Commands executed
   - Infrastructure changes with exact resource names
   - Architecture decisions and reasoning
7. Upload post to appropriate S3 bucket
8. Invalidate CloudFront cache (all four distributions)

The generator preserves technical detail—exact S3 bucket names, CloudFront distribution IDs, Route53 zone IDs, Python function names, and file paths—while removing all credentials. This allows developers to understand exactly what changed and why, without security exposure.

Integration with Ship's Papers Navigation

Each sailing property's main navigation received an updated dropdown structure. The Ship's Papers menu now includes a "Technical Blog" link pointing to the appropriate tech.[domain].com. For example, in /Users/cb/Documents/repos/sites/queenofsandiego.com/index.html, the Ship's Papers menu now contains:

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

This makes technical documentation discoverable by stakeholders browsing normal site navigation, supporting the goal of transparency without requiring special access or knowledge of technical infrastructure.

Content Filtering Strategy

The blog generator uses a multi-layer filtering approach:

  • Pattern-based filtering: Regular expressions match common credential formats (AWS key patterns, JWT structures, password fields)
  • Context-aware filtering: File paths and commands that reference credentials are redacted (e.g., "Read repos.env" becomes "Check environment configuration")
  • Manual review checkpoints: Generated posts include markers for sensitive data that may have survived pattern matching, flagging them for manual review before publication
  • Domain isolation: Posts only include work related to their specific property; cross-domain changes are tagged as infrastructure-wide

Key Technical Decisions

Why CloudFront + S3? Static HTML blogs don't require compute. S3 + CloudFront provides edge caching, automatic HTTPS (via ACM certificates), and zero-maintenance hosting. CloudFront also enables instant cache invalidation when new posts publish.

Why mixed DNS providers? Rather than migrating all domains to Route53, the system works with existing registrars. This reduces operational risk and DNS propagation delays.

Why session-based generation? Capturing at session end ensures maximum detail capture. The JSONL transcript format provides structured tool use data that's easy to parse programmatically.

Why granular filtering? High-level summaries hide important decisions. Sergio needs to see file paths, function names, and exact infrastructure changes. The filtering removes only credentials, preserving all technical substance.

What's Next

The system is live and will begin publishing posts on next session stop. Short-term improvements include:

  • Template customization per property (branding, sidebar navigation)
  • Search/archive functionality across posts
  • Automated anomaly detection (flags unusual file access patterns)
  • Integration with the existing progress board to link technical posts to task cards
  • Historical bulk-generation from past session transcripts

The foundation is solid: four independent tech blogs with identical infrastructure patterns, automatic generation on session end, and aggressive credential filtering. This provides complete transparency for technical stakeholders while maintaining security.

```