podcastdistributiona/README.md

# 🎙️ PodcastYes

An all-in-one AI platform that takes you from a topic idea to a finished, publishable
podcast episode in minutes — it writes the **script** (GPT-4), records realistic
**multi-voice audio** (ElevenLabs), and designs the **cover art** (DALL·E), then lets
you fine-tune, download, and repurpose the result.

## Stack

| Concern | Choice |
| --- | --- |
| Framework | Next.js (App Router) + TypeScript |
| UI | Tailwind CSS + shadcn/ui + Recharts |
| Database | PostgreSQL + Prisma |
| Auth | Better Auth (email/password + Google, admin + organization plugins) |
| Queue | **pg-boss** (Postgres-backed, no Redis) + a separate worker process |
| Storage | Local disk on a persistent volume (swappable `StorageProvider` → S3/R2) |
| AI | OpenAI (GPT-4 + DALL·E), ElevenLabs (TTS + dialogue) |
| Billing | **Stripe and PayPal** → one unified `Subscription` model |
| Email | Resend |
| Deploy | **Dokploy** (Docker Compose + Traefik) — see [`deploy/README.md`](deploy/README.md) |

## Architecture

```
Browser ──► Next.js web (PM2)  ──enqueue──►  Postgres (app data + pgboss queue)
                │  SSE status                      ▲ claim job (SKIP LOCKED)
                ▼                                   │
          /api/assets (private mp3)          Worker (PM2, ffmpeg)
                                              script → segment → ElevenLabs
                                              → ffmpeg stitch → DALL·E → save → meter
                                                       │
                                                       ▼
                                              Local disk  storage/{mp3,art}
```

## Local development

```bash
npm install
cp .env.example .env        # fill DATABASE_URL, BETTER_AUTH_SECRET, OPENAI_API_KEY, ELEVENLABS_API_KEY…
npx prisma migrate dev      # create tables
npm run db:seed             # seed the plan catalog

# Two processes:
npm run dev                 # web (http://localhost:3000)
npm run worker:dev          # generation worker (needs ffmpeg on PATH)
```

`ffmpeg` must be installed and on `PATH` for audio stitching
(`brew install ffmpeg` / `apt install ffmpeg` / `choco install ffmpeg`).

Make yourself an admin after signing up:

```bash
npm run make-admin you@email.com   # then visit /admin
```

## Key directories

```
app/(marketing)   public landing + pricing
app/(auth)        sign-in / sign-up / password reset
app/(app)         user dashboard (episodes, wizard, usage, billing, team, api-keys, settings)
app/(admin)       admin dashboard (users, subscriptions, AI cost, moderation, health, flags, audit)
app/api           auth, webhooks/{stripe,paypal}, episodes/[id]/stream (SSE), assets, v1 (API)
lib/ai            provider abstraction + pipeline (generate-episode, segment, stitch, repurpose)
lib/billing       plans, stripe, paypal, catalog, unified subscription writer, webhooks
lib/queue         pg-boss client + job definitions
lib/storage       StorageProvider interface + local-disk impl
worker/           pg-boss consumer (runs the generation pipeline)
```

## How generation works

1. The 3-step wizard creates an `Episode (QUEUED)` + speaker config, then enqueues a
   pg-boss job (after `enforceLimit` checks the plan).
2. The worker runs the pipeline, updating `Episode.status` at each stage.
3. The episode page subscribes to `/api/episodes/[id]/stream` (SSE) and shows a live
   stepper, then renders the script editor, audio player, and cover art when `READY`.

Long scripts are chunked to stay under ElevenLabs' ~2k-char dialogue limit, synthesized
per segment, then concatenated and loudness-normalized with ffmpeg.

## Deployment

Containerized for **Dokploy** (Docker Compose: `web` + `worker`, Traefik for
domain/TLS/SSE, a persistent `storage` volume). See [`deploy/README.md`](deploy/README.md)
for the full runbook (env, domain, migrations-on-boot, webhooks, backups).