# ClassBuild

> AI-powered course generator that takes a topic and produces a complete, ready-to-teach university course — interactive HTML chapters, gamified quizzes, PowerPoint slides, AI-narrated audiobooks, infographics, and teaching packs — all grounded in five evidence-based learning science principles. Built with TypeScript, React 19, Vite 7, and Claude.

ClassBuild operates as both a browser app (React + Zustand + Vite at localhost:5173) and a headless CLI (`scripts/generate-course.ts`). API keys are bring-your-own: Anthropic Claude (required), Google Gemini (optional, covers infographics and voice narration via Gemini TTS).

## Architecture

The codebase has two entry points sharing the same generation core:

- **Browser app**: React 19 SPA with Zustand stores (`src/store/`), Tailwind CSS 4, Framer Motion. Pages follow the pipeline stages: Setup, Syllabus, Research, Build, Export.
- **CLI**: `scripts/generate-course.ts` — headless Node.js script using `tsx`. Runs the same prompt builders and Claude streaming functions without a browser. Supports parallel research (3 chapters concurrently) and parallel material generation per chapter.

Key directories:
- `src/prompts/` — All LLM prompt builders (system + user prompts for each generation stage)
- `src/services/claude/` — Anthropic SDK client, streaming with retry, model constants
- `src/services/gemini/` — Image generation for infographics and text-to-speech (chunked at 2800 chars; PCM wrapped as WAV)
- `src/services/export/` — PPTX, quiz DOCX, and publish exporters
- `src/services/quiz/` — Answer balancer for quiz generation
- `src/types/` — TypeScript interfaces for the entire domain model
- `src/themes.ts` — Four visual themes (Midnight, Classic, Ocean, Warm) with full color specs
- `src/templates/` — HTML templates for course viewer and quizzes
- `src/store/` — Zustand stores: `courseStore` (generation state), `apiStore` (keys), `uiStore`
- `scripts/lib/` — CLI-only helpers: publish assembler, DOCX builders, Node image generation

## Generation Pipeline

The pipeline has five stages, each with dedicated prompt builders in `src/prompts/`:

1. **Setup** (`CourseSetup` type) — User defines topic, audience level, chapter count, theme, teaching environment, and notes.
2. **Syllabus** (`src/prompts/syllabus.ts`) — Claude Opus designs the full course arc. Outputs JSON with chapter titles, narratives, key concepts, widget specs, learning science annotations, and spacing connections. Parsed into `Syllabus` type.
3. **Research** (`src/prompts/research.ts`) — Claude with web search gathers real-world sources per chapter. Produces `ResearchDossier` with verified/unverified sources, DOIs validated via `src/utils/doiValidator.ts`.
4. **Build** — Per chapter, generates all materials in parallel where possible:
   - **Chapter HTML** (`src/prompts/chapter.ts`) — Standalone HTML with embedded interactive widgets, themed CSS, and reading progress bar
   - **Practice quiz** (`src/prompts/practiceQuiz.ts`) — Gamified quiz with confidence calibration
   - **In-class quiz** (`src/prompts/inClassQuiz.ts`) — 5 shuffled versions + answer keys
   - **Discussion questions** (`src/prompts/discussion.ts`)
   - **Activities** (`src/prompts/activities.ts`) — Facilitated activities with step-by-step guides
   - **Audio transcript** (`src/prompts/audioTranscript.ts`) — Narration script sent to Gemini TTS
   - **Slides** (`src/prompts/slides.ts`) — JSON slide data rendered to PPTX via pptxgenjs
   - **Weekly challenge** (`src/prompts/weeklyChallenge.ts`) — Mastery-gated assessment with 6 question types, parameterised variants, SCORM 2004 wrapper for Blackboard
   - **Infographic** (`src/prompts/infographic.ts`) — Claude writes a prompt, Gemini generates the image
5. **Export/Publish** (`scripts/lib/publish.ts`) — Assembles a static course viewer site from all generated materials, or exports as ZIP/PPTX.

## CLI Usage

```
ANTHROPIC_API_KEY=sk-... npx tsx scripts/generate-course.ts \
  --topic "The Psychology of Prejudice" \
  --chapters 12 \
  --level advanced-undergrad \
  --theme midnight \
  --length comprehensive \
  --notes "Use international and Australian examples." \
  --output ./output/prejudice
```

Flags:
- `--topic` (required): Course topic
- `--chapters` (default 12): Number of chapters
- `--level` (default advanced-undergrad): `general-public`, `professional`, `advanced-undergrad`
- `--theme` (default midnight): `midnight`, `classic`, `ocean`, `warm`
- `--length` (default standard): `concise`, `standard`, `comprehensive`
- `--widgets` (default 3): Interactive widgets per chapter
- `--cohort` (default 60): Expected class size
- `--environment` (default lecture-theatre): `lecture-theatre`, `collaborative`, `flat-classroom`, `online-hybrid`
- `--notes`: Additional context for the AI
- `--voice-id`: Gemini TTS voice name for audiobook narration (e.g. `Kore`, `Puck`, `Charon`)
- `--syllabus`: Path to existing syllabus.json (skip regeneration)
- `--stop-after`: `syllabus` or `research` — stop early for review
- `--no-publish`: Skip course viewer assembly

Environment variables: `ANTHROPIC_API_KEY` (required), `GEMINI_API_KEY` (optional — enables infographics and TTS). Install `ffmpeg` if you want the CLI to transcode WAV audio to MP3.

## AI Models and Services

Claude models (`src/services/claude/client.ts`):
- `claude-opus-4-6` — Syllabus design and chapter writing (high-quality, extended thinking)
- `claude-sonnet-4-6` — Quizzes, discussions, activities, slides, research (fast, parallel tasks)
- `claude-haiku-4-5` — Lightweight tasks

Extended thinking budgets: `max` (32k tokens), `high` (16k), `medium` (8k), `low` (4k).

Streaming (`src/services/claude/streaming.ts`): All Claude calls use streaming with retry. Callbacks for `onText`, `onThinking`, `onToolUse`, `onWebSearch`, `onWebSearchResults`, `onDone`, `onError`.

Gemini TTS (`src/services/gemini/tts.ts`): Text-to-speech using `gemini-2.5-flash-preview-tts`. Text chunked at 2800 chars respecting paragraph/sentence boundaries to avoid quality drift. PCM (24 kHz, 16-bit, mono) concatenated into a single WAV container. Default voice: `Kore`. Retries transient 5xx errors per the Gemini docs.

Gemini Images (`src/services/gemini/imageGen.ts`): Generates infographic images from Claude-written prompts. Serialized requests with retry and backoff.

## Core Types

Defined in `src/types/course.ts`:

- `CourseSetup` — Input configuration: topic, level, chapters, theme, environment, notes
- `Syllabus` — Course blueprint: title, overview, array of `ChapterSyllabus`
- `ChapterSyllabus` — Per-chapter plan: title, narrative, keyConcepts, widgets (`WidgetSpec[]`), scienceAnnotations, spacingConnections
- `GeneratedChapter` — All outputs for one chapter: htmlContent, practiceQuizData, inClassQuizData, discussionData, activityData, audioTranscript, audioUrl, slidesJson, infographicDataUri
- `ResearchDossier` — Sources per chapter with verification status
- `SlideData` — Individual slide: title, bullets, speakerNotes, layout type
- `EducationLevel` — `high-school`, `first-year`, `advanced-undergrad`, `postgraduate`, `professional`, `general-public`
- `ChapterLength` — `concise` (2k words), `standard` (4k words), `comprehensive` (6k words)
- `SciencePrinciple` — `spacing`, `interleaving`, `retrieval`, `examples`, `dual-coding`
- `BloomLevel` — `remember`, `understand`, `apply`, `analyze`, `evaluate`, `create`

Generation tracking (`src/types/generation.ts`):
- `GenerationStatus` — `idle`, `generating`, `complete`, `error`
- `GenerationProgress` — Stage, chapter number, step, progress percentage, streamed text

## Learning Science Principles

Every prompt instructs Claude to embed these five evidence-based principles:

1. **Spacing** (Distributed Practice) — Key concepts reappear across chapters with increasing complexity. `spacingConnections` in syllabus maps cross-chapter links.
2. **Interleaving** — Related topics from different chapters are mixed in practice and examples.
3. **Retrieval Practice** (Testing Effect) — Built-in "Think About It" prompts and confidence-calibrated quizzes.
4. **Concrete Examples** — Abstract theories grounded in vivid, real-world cases with named people and specific studies.
5. **Dual Coding** — Every concept gets verbal and visual representation through interactive widgets and infographics.

The syllabus stage annotates each chapter with `ScienceAnnotation[]` specifying which principles are emphasized and how.

## Themes

Four themes defined in `src/themes.ts`, each with full color system (pageBg, cardBg, accent, text colors, fonts). The `buildThemePromptBlock()` function injects theme colors into Claude prompts so generated HTML matches the chosen theme.

- **Midnight** — Dark purple/violet, system-ui headings, Georgia body
- **Classic** — Light cream/navy, Georgia throughout
- **Ocean** — Dark blue/cyan, system-ui throughout
- **Warm** — Light warm/orange, Georgia headings, Lora body

## Voice Options

Gemini TTS voices (`src/themes.ts`):
- Kore — Firm, confident default narrator
- Puck — Upbeat, energetic
- Charon — Informative, measured (lecture-friendly)
- Sulafat — Warm, approachable
- Rasalgethi — Clear, knowledgeable (technical topics)
- Leda — Youthful, expressive

## Key Source Files

- `scripts/generate-course.ts`: Headless CLI entry point — arg parsing, pipeline orchestration, file I/O
- `scripts/lib/publish.ts`: Static course viewer assembler
- `scripts/lib/coursePackageTemplate.ts`: HTML template for published course viewer
- `scripts/lib/docx-helpers.ts`: DOCX generation for discussion, activities, transcript, research, syllabus
- `scripts/lib/node-image.ts`: Node.js Gemini image generation
- `scripts/lib/node-image-placer.ts`: Replaces Gemini image placeholders in chapter HTML
- `scripts/gen-audio.ts`: Standalone audio generation script
- `src/services/claude/client.ts`: Anthropic SDK singleton, model constants, thinking budgets
- `src/services/claude/streaming.ts`: Streaming with retry, web search integration
- `src/services/gemini/tts.ts`: Gemini text-to-speech with chunking, retry, and WAV wrapping
- `src/services/gemini/imageGen.ts`: Gemini image generation with retry
- `src/services/gemini/imagePlacer.ts`: Browser-side image placeholder replacement
- `src/services/export/pptxExporter.ts`: PowerPoint generation via pptxgenjs
- `src/services/export/quizDocExporter.ts`: Quiz document export
- `src/services/quiz/answerBalancer.ts`: Ensures balanced answer distributions
- `src/store/courseStore.ts`: Zustand store — central state for generation pipeline
- `src/store/apiStore.ts`: API key management store
- `src/prompts/syllabus.ts`: Syllabus prompt builder — the architectural blueprint prompt
- `src/prompts/chapter.ts`: Chapter HTML prompt with full CSS template injection
- `src/prompts/research.ts`: Research/web search prompt
- `src/prompts/practiceQuiz.ts`: Gamified practice quiz prompt
- `src/prompts/inClassQuiz.ts`: In-class quiz prompt (5 versions)
- `src/prompts/discussion.ts`: Discussion questions prompt
- `src/prompts/activities.ts`: Teaching activities prompt
- `src/prompts/audioTranscript.ts`: Audio narration transcript prompt
- `src/prompts/slides.ts`: Slide deck JSON prompt
- `src/prompts/infographic.ts`: Infographic meta-prompt (Claude writes prompt for Gemini)
- `src/prompts/learningObjectives.ts`: Bloom's taxonomy learning objectives
- `src/types/course.ts`: All domain types and interfaces
- `src/types/generation.ts`: Generation status and progress types
- `src/themes.ts`: Theme definitions, theme prompt block builder, voice options
- `src/templates/quizTemplate.ts`: Interactive quiz HTML template
- `src/templates/courseViewerTemplate.ts`: Course viewer HTML template
- `src/utils/doiValidator.ts`: DOI validation for research sources