Briefcast

A personal podcast generator. You pick the topics you care about, a format, and how often you want an episode; on that schedule it gathers recent news, writes an editorial script, and synthesizes it into a narrated MP3 you can play in the app. Built with Next.js (App Router), Postgres + Prisma, a pg-boss job queue, and a standalone worker that calls Tavily (news), OpenAI (script), and ElevenLabs (audio).

The setup below runs the full pipeline locally — add your OpenAI / ElevenLabs / Tavily keys and you'll generate a real episode in a couple of minutes. Architecture, decisions, and tradeoffs live in DESIGN.md.

Local development

Prerequisites: Docker, Node.js 20+, pnpm 10 (corepack enable provisions the pinned version), and ffmpeg on your PATH (brew install ffmpeg / apt install ffmpeg — the worker uses it to join the audio).

1. Install and create your .env.

pnpm install
cp .env.example .env

.env.example ships with working local defaults and is annotated key-by-key; everything except the provider keys works as-is.

2. Add your provider keys to .env:

• OPENAI_API_KEY — create one at platform.openai.com.
• ELEVENLABS_API_KEY — sign up at elevenlabs.io and copy the key from your profile.
• TAVILY_API_KEY — the news-search provider; create a free account at tavily.com and copy the key from the dashboard.

3. Start the local services and apply the schema.

docker compose up -d           # Postgres + MinIO (object storage), with the bucket auto-created
pnpm db:migrate && pnpm seed   # apply migrations, then seed the dev account and a sample episode

4. Run the app and worker.

pnpm dev

This runs the Next.js app and the generation worker together (via concurrently). If you haven't set the provider keys, the worker logs the missing keys and exits — everything else keeps running, so you can still browse the app and the seeded episode.

5. Sign in at http://localhost:3000 with demo@briefcast.local / password123 (the form is prefilled).

6. Generate an episode. The seeded account already has a feed and one ready-to-play episode (from sample.mp3), so the UI works the moment you sign in. For a fresh run, open Preferences, set the cadence to Test — every 2 min, and the next 2-minute boundary kicks off a real generation — the episode fills in as it moves through gathering news → writing script → synthesizing audio → ready.

Also handy while developing

• pg-boss job dashboard — pnpm dashboard runs it on localhost:3001 (not started by pnpm dev).
• MinIO console (stored audio) — localhost:9001 (minioadmin / minioadmin).
• Reset the database — pnpm db:reset && pnpm seed drops and rebuilds from scratch.

What's real, what's mocked

• The pipeline is the real thing. With the keys set, generation runs live news research, an LLM-written script, and synthesized audio — not a canned response.
• Everything runs locally. Postgres and object storage (MinIO) run in Docker; the only outbound calls are to the three providers during generation.
• The dashboard metrics are mocked. The dashboard at /dashboard uses mocked-but-derived data — see DESIGN.md.
• This is a local setup, not production. One seeded user and a deliberately minimal credentials login; see DESIGN.md for what deploying would add.

Configuration

.env.example is annotated key-by-key; copy it to .env and the only values you fill in are the three provider keys. The keys that matter:

Variable	Default	Notes
DATABASE_URL	local Postgres on :5433	matches docker compose
AUTH_SECRET	dev placeholder	fine for local
OPENAI_API_KEY / ELEVENLABS_API_KEY / TAVILY_API_KEY	empty	required to generate episodes
S3_*	local MinIO (minioadmin)	matches docker compose
WORKER_CONCURRENCY	1	episodes generated per worker process

The three keys map to the pipeline stages: OPENAI_API_KEY writes the script, ELEVENLABS_API_KEY synthesizes the audio, and TAVILY_API_KEY finds and extracts the news; synthesis also needs ffmpeg on your PATH.

Useful scripts

All run from the repo root.

Command	What it does
pnpm dev	run the app and worker together
pnpm seed	seed the dev account and episode
pnpm db:migrate	apply migrations
pnpm db:reset	drop and re-apply every migration (follow with pnpm seed)
pnpm dashboard	pg-boss job dashboard on :3001
pnpm test / pnpm typecheck / pnpm lint	unit tests and checks (also run in CI)

Architecture and tradeoffs

DESIGN.md covers the architecture, the decisions behind it, the known limitations, and what production deployment would take. The codebase is a pnpm workspace: apps/web (Next.js UI, auth, and the job producer), apps/worker (the generation pipeline), and shared packages/core and packages/db.