Epoch Pod

AI-powered historical storytelling in multiple immersive formats.

Epoch Pod is a multi-format history platform that generates personalized podcast content through AI. Experience history through narrative podcasts, interviews with historical figures, interactive debates, and choose-your-own-adventure stories. All delivered via email and RSS feeds compatible with Apple Podcasts and other podcast apps.

Features

🎭 Multiple Episode Formats

Narrative Podcasts: Traditional 5-act storytelling with citations and sources
Historical Interviews: AI-powered conversations with figures like Einstein, Cleopatra, and Ada Lovelace
Interactive Debates: Two-sided arguments on controversial topics with real-time voting
Choose Your Own Adventure: Branching narrative journeys where your choices shape history

🤖 AI-Powered Generation

Multi-Voice Audio: 2-3 different AI voices for interviews and debates
Structured Outputs: Zod-validated schemas ensure consistent quality
Historical Accuracy: Built-in citation and source tracking
Branching Narratives: Complex decision trees with path validation

📧 Delivery & Distribution

Email Delivery: Beautiful HTML emails with React Email components and RFC 8058 one-click unsubscribe
RSS Feeds: Standards-compliant feeds with Podcasting 2.0 transcript tags
Personalization: Per-user topics, voice preferences, and delivery cadence
Apple Podcasts Ready: Byte-range support, proper enclosures, and validated feeds

🎨 User Experience

Interactive Voting: Vote on debates and unlock follow-up episodes based on community results
Journey Tracking: Adventures remember your progress across sessions
SEO Optimized: JSON-LD structured data, dynamic OG images, and comprehensive metadata
Accessibility: Full transcripts and WCAG 2.1 AA compliance

Architecture

Monorepo Structure

apps/
  web/                 # Next.js App Router application
    app/
      (marketing)/     # Public marketing pages
      dashboard/       # User dashboard
      episodes/        # Episode pages
      api/
        rss/           # RSS feed endpoints
        generate/      # Episode generation
        webhooks/      # Email webhooks
    lib/               # Core libraries
    components/        # React components
    emails/            # React Email templates

packages/
  schema/              # Zod schemas for structured outputs
  agent/               # AI agent toolkit (optional)

prisma/                # Database schema and migrations

Tech Stack

Framework: Next.js 15 (App Router)
Database: PostgreSQL + Prisma ORM
Authentication: Auth.js (NextAuth v5)
Email: Resend + React Email
Storage: Vercel Blob
AI: OpenAI (GPT-4 + TTS)
TTS: OpenAI TTS / ElevenLabs
Styling: Tailwind CSS
Type Safety: TypeScript + Zod

Getting Started

Prerequisites

Node.js 18.17+
PostgreSQL database
OpenAI API key
(Optional) ElevenLabs API key
(Optional) Resend API key

Quick Start (Recommended)

We provide setup scripts that handle installation, database migration, and sample data in one command:

Linux/macOS:

git clone https://github.com/risban933/Epoch.git
cd Epoch
./scripts/setup-dev.sh

Windows:

git clone https://github.com/risban933/Epoch.git
cd Epoch
scripts\setup-dev.bat

This will:

Install all dependencies
Run database migrations
Seed sample content (2 interviews, 2 debates, 1 adventure with 11 episodes)
Provide next steps for running the dev server

Manual Installation

Clone the repository:

git clone https://github.com/risban933/Epoch.git
cd Epoch

Install dependencies:

npm install

Set up environment variables:

cp apps/web/.env.example apps/web/.env.local

Edit apps/web/.env.local with your configuration:

DATABASE_URL="postgresql://user:password@localhost:5432/epochpod"
AUTH_SECRET="generate-with-openssl-rand-base64-32"
OPENAI_API_KEY="sk-..."
RESEND_API_KEY="re_..."
BLOB_READ_WRITE_TOKEN="vercel_blob_..."

Initialize the database:

cd apps/web
npx prisma migrate dev
npx prisma generate

(Optional) Seed sample data:

npx prisma db seed

Start the development server:

cd ../..
npm run dev

Visit http://localhost:3000 to see the app.

Sample Content

After seeding, you'll have access to:

Interviews: Albert Einstein on Relativity, Cleopatra on Egyptian Politics
Debates: Napoleon (Tyrant or Reformer?), Columbus (Explorer or Colonizer?)
Adventures: Roman Senator's Dilemma (11-episode branching narrative)

Development

Database

# Push schema changes (development)
npm run db:push

# Create a migration
npm run db:migrate

# Open Prisma Studio
npm run db:studio

Type Checking

npm run type-check

Linting

npm run lint

Deployment

Vercel (Recommended)

Push your code to GitHub
Import the project in Vercel
Configure environment variables
Deploy!

Vercel automatically:

Builds the Next.js app
Provisions Vercel Blob storage
Enables byte-range requests for audio
Configures serverless functions

RSS Feed

After deployment, your RSS feed will be available at:

Public feed: https://your-domain.com/api/rss
Private feeds: https://your-domain.com/api/rss/[userId]?token=...

Apple Podcasts Submission

Validate your feed at https://podba.se/validate/
Ensure artwork meets Apple's specs (square, 1400x1400 minimum)
Submit via Apple Podcasts Connect
Wait for approval (typically 1-3 days)

Content Generation Pipeline

Narrative Podcasts

Outline: AI drafts 5-act narrative structure with citations
Script: Expands outline into 1,200-1,800 word narration
Audio: TTS converts script to MP3 with proper metadata
Storage: Uploads to Blob storage with byte-range support
Publish: Updates RSS feed and sends email notifications

Historical Interviews

Outline: AI generates guest biography, questions, and context
Script: Creates dialogue between host and historical figure
Audio: Multi-voice TTS with different voices for host and guest
Storage: Uploads audio with metadata
Publish: Makes available with interactive transcript

Interactive Debates

Outline: AI researches topic and formulates both positions
Script: Generates structured arguments with evidence
Audio: Three-voice generation (moderator + 2 debaters)
Storage: Uploads with voting metadata
Publish: Enables voting and follow-up episode unlocking

Choose Your Own Adventure

Outline: AI creates branching narrative tree with 8-12 nodes
Validation: Ensures all paths are valid and reachable
Scripts: Generates individual scripts for each node
Audio: Creates separate audio files for all nodes
Storage: Uploads all episodes with connection metadata
Publish: Enables journey tracking and choice selection

Email Compliance

Epoch Pod follows best practices for email deliverability:

✅ SPF, DKIM, and DMARC authentication
✅ List-Unsubscribe header (RFC 2369)
✅ List-Unsubscribe-Post one-click (RFC 8058)
✅ Bounce and complaint handling via webhooks
✅ Gmail/Yahoo 2024 bulk sender requirements

Accessibility

Full transcripts on episode pages
Downloadable transcript files
Keyboard-accessible audio player
ARIA labels and semantic HTML
WCAG 2.1 AA compliance

Project Status

✅ Completed (Phases 1-9)

Phase 1: Project Scaffolding

Next.js 15 App Router with TypeScript
Monorepo structure (apps/web, packages/schema, packages/agent)
Prisma schema with 16 models (expanded from 6)
Zod schemas for structured AI outputs
ESLint, Prettier, Tailwind CSS configuration

Phase 2: Authentication & Database

Auth.js (NextAuth v5) with Prisma adapter
Email magic link authentication via Resend
Protected dashboard with middleware
Session management (JWT strategy)
Auth pages (signin, signout, verify-request, error)

Phase 3: AI Content Generation (Narrative)

OpenAI integration with structured outputs
Outline generator (5-act narrative structure)
Script expansion service (1,200-1,800 words)
TTS adapter abstraction (OpenAI TTS + ElevenLabs)
Audio generation with streaming support
Episode generation orchestrator

Phase 4: Storage & Media Hosting

Vercel Blob integration
Audio upload service with metadata tracking
Byte-range (HTTP 206) support verification
Automatic CDN caching

Phase 5: RSS Feed Generation

RSS 2.0 feed builder with iTunes tags
Podcasting 2.0 transcript tags
Public feed endpoint (/api/rss)
Private personalized feeds (/api/rss/[userId])
Feed validation utilities
Apple Podcasts compliance

Phase 6: Email Delivery System

React Email templates (episode notification, digest)
Email service with RFC 8058 one-click unsubscribe
Webhook handlers for bounces/complaints
Email event tracking
Resend integration with proper headers
Auto-unsubscribe on hard bounce/complaint

Phase 7: Frontend UI & UX

Public episodes list page
Individual episode page with transcript
Dashboard episodes management
Accessible audio player with keyboard controls
User preferences page (topics, voice, cadence)
Private RSS feed URL management
Responsive design with dark mode

Phase 8: SEO & Metadata

JSON-LD structured data (PodcastSeries, PodcastEpisode, Organization, Website)
Dynamic sitemap.xml with all published episodes
robots.txt with podcast crawler allowlist
Dynamic OG image generation for episodes (Next.js ImageResponse)
Root-level OG image for homepage
Enhanced Metadata API with OpenGraph and Twitter Cards
Breadcrumb navigation schema

Phase 9: Multi-Format Content (NEW!)

📋 Upcoming (Phases 10-14)

Background jobs (Vercel Cron for scheduled generation)
Testing infrastructure (Jest, Playwright, E2E tests)
CI/CD pipeline (GitHub Actions)
Security hardening (CSP headers, RBAC)
Apple Podcasts submission
AI Agent toolkit (optional)
Social sharing features
Analytics dashboard
User-generated content moderation

📊 Statistics

Total Files Created: 115+
Lines of Code: ~23,500+
Commits: 14+
Database Models: 16 (from 6)
API Endpoints: 28+ (from 17)
UI Components: 15+ (from 8)
Phases Completed: 9 of 14 (64%!)

Contributing

This is currently a personal project, but suggestions and feedback are welcome!

License

See LICENSE file for details.

Built with ❤️ for history enthusiasts everywhere.

Name		Name	Last commit message	Last commit date
Latest commit History 50 Commits
apps/web		apps/web
docs		docs
lib		lib
packages		packages
prisma		prisma
scripts		scripts
.gitattributes		.gitattributes
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
FEATURE_PLANS.md		FEATURE_PLANS.md
IMPLEMENTATION_STATUS.md		IMPLEMENTATION_STATUS.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

License

rishabhcli/Epoch

Folders and files

Latest commit

History

Repository files navigation

Epoch Pod

Features

🎭 Multiple Episode Formats

🤖 AI-Powered Generation

📧 Delivery & Distribution

🎨 User Experience

Architecture

Monorepo Structure

Tech Stack

Getting Started

Prerequisites

Quick Start (Recommended)

Manual Installation

Sample Content

Development

Database

Type Checking

Linting

Deployment

Vercel (Recommended)

RSS Feed

Apple Podcasts Submission

Content Generation Pipeline

Narrative Podcasts

Historical Interviews

Interactive Debates

Choose Your Own Adventure

Email Compliance

Accessibility

Project Status

✅ Completed (Phases 1-9)

📋 Upcoming (Phases 10-14)

📊 Statistics

Contributing

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

Packages