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:

---
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