crashtestdev/.amplifier/BLOG_ARCHITECTURE.md

# Blog Architecture: Crash Test Dev

## What We're Building

A blog for lessons, patterns, and writing. Elegant like the Amplifier Masterclass
site. Read-aloud feature. No AI slop. Ken's voice throughout.

## Reference: What the Masterclass Does Right

The masterclass site (anderlpz.github.io/amplifier-masterclass/) achieves its
elegance through:

- **Three-font stack**: Serif body (Source Serif 4), sans headings (Inter), mono
  code (JetBrains Mono). The serif/sans pairing is the single biggest quality signal.
- **18px base, 1.75 line-height**: Generous reading. Feels like a printed essay.
- **Muted color palette**: Cool lavender-grey background (#F4F5F9), body text in
  secondary grey (#5C5E6E) not black, muted steel blue accent (#3E5C8A).
- **720px reading column + 840px breakout**: Prose narrow, code/diagrams wider.
  Creates visual breathing rhythm.
- **Pre-recorded narration**: OpenAI TTS voices (Fable, Nova, Alloy), 3 choices,
  with full transport controls, scrubber, speed selection, auto-advance.
- **Progressive disclosure**: TOC pill, drawer, inline term definitions, xref
  hovers, scroll-driven diagram revelation.
- **Zero framework bloat**: Hand-crafted HTML/CSS/JS. Every pixel intentional.

## Tech Decision: Astro

**Current stack (Gatsby 2)**: Dead framework. React 16. gatsby-theme-blog 1.0.
Not worth upgrading -- better to start fresh.

**Recommended: Astro**
- Same framework the masterclass uses for its component rewrite
- Ships zero JS by default. JS only where explicitly needed (audio player, TOC)
- Markdown/MDX content with frontmatter. Content-first architecture
- Built-in code highlighting (Shiki), image optimization, RSS
- Minimal deps: just astro + typescript, like the masterclass

**Why not Next.js/Remix**: Over-engineered for a blog. Ken's content doesn't
need server-side rendering or API routes. Static generation + islands is the
right fit.

## Design Approach

Inspired by the masterclass but adapted for a multi-post blog (not single-page
document):

### Typography
| Role | Font | Why |
|------|------|-----|
| Body prose | Lora or Source Serif 4 | Serif signals "read this slowly" |
| Headings, UI | Inter | Clean, modern, tight tracking |
| Code | JetBrains Mono or Berkeley Mono | Monospaced with personality |

### Color
Warm variation on the masterclass palette:
- Background: warm paper (#F4F2ED or similar) -- not cool lavender
- Surface: white cards
- Text: near-black (#1A1815), secondary grey for body
- Accent: deep blue or muted violet (Ken's existing blog uses #007acc)
- No dark mode initially (the masterclass explicitly chose this)

### Layout
- 650-720px reading column, centered
- Code blocks break wider (840-900px)
- Generous vertical spacing between sections (64px+ for h2 breaks)
- Fixed minimal nav at top (site title, optional TOC pill for long posts)

### Content Structure
```
/                          Index -- list of posts, most recent first
/posts/[slug]              Individual post pages
/patterns/[slug]           Technical patterns (shorter, reference-style)
/lessons/[slug]            Longer lesson-format pieces
```

Frontmatter:
```yaml
---
title: "Speeding Up Webpack Typescript Incremental Builds by 7x"
date: 2019-08-16
type: post | pattern | lesson
tags: [webpack, typescript, performance]
audio: true  # triggers TTS generation
summary: "One-sentence hook for the index page"
---
```

## Read-Aloud Feature

### How the Masterclass Does It
- Pre-generated MP3s per chapter using OpenAI TTS API
- 3 voice options (Fable, Nova, Alloy)
- Script files that are spoken-word summaries, NOT verbatim text reads
- Full transport controls (play/pause, skip, scrub, speed, voice select)

### Our Approach
Same pattern, adapted for blog posts:

1. **Generate at build time or on-demand**: For each post with `audio: true`,
   generate a narration script (spoken-word summary, not verbatim) and run
   it through OpenAI TTS.

2. **Narration script generation**: Use the VOICE.md profile to write
   spoken versions. Key rules from the masterclass:
   - Don't read code blocks aloud. Describe what they do.
   - Don't read URLs. Say "I've linked the PR in the post."
   - Keep the conversational energy. This should sound like Ken
     explaining it to you at a whiteboard.

3. **Audio player component**: Minimal pill in the nav area. Click to
   expand transport controls. Single voice initially (can add multiple
   later).

4. **Per-post, not per-section**: Unlike the masterclass's per-chapter
   audio, blog posts are short enough for single-track narration.

### TTS Pipeline
```
content/posts/my-post.md
  --> narration-script generator (strips code, converts to spoken prose)
  --> OpenAI TTS API (voice: "fable" or "nova")
  --> public/audio/my-post.mp3
  --> referenced in post frontmatter
```

## Migration Path

### Phase 1: Foundation
- New Astro project in this repo (replace Gatsby)
- Design tokens (CSS custom properties, no Tailwind)
- Base layout, typography, color
- Markdown/MDX content pipeline
- Migrate 2 existing posts

### Phase 2: Polish
- Audio player component (pill + transport)
- Generate narration for existing posts
- Index page design
- Code block styling (breakout width, optional filenames)
- RSS feed

### Phase 3: Content Types
- Pattern pages (shorter, reference-style)
- Lesson pages (longer, progressive disclosure)
- Cross-references between related content

### Phase 4: Advanced
- Scroll-synced TOC for long posts (like the masterclass)
- Inline term definitions (if building a technical vocabulary)
- Reading progress indicator
- Multiple TTS voices