A curated archive of AI-powered podcast summaries. New podcasts and episodes are added by the admin. Visitors browse, read, subscribe via RSS, or request a podcast to be added.

Live at tldl-pod.com

• Node.js 18+
• Wrangler CLI
• Cloudflare account with Workers, KV, Queues, and Durable Objects enabled
• API keys: OpenAI, Podcast Index (free at podcastindex.org)

# Install dependencies
npm install

# Create .dev.vars with your secrets
cat > .dev.vars << 'EOF'
OPENAI_API_KEY=sk-...
PODCAST_INDEX_KEY=...
PODCAST_INDEX_SECRET=...
TURNSTILE_SECRET=...
EOF

# Start dev server
npm run dev
# → http://localhost:8787

Populate local dev with sample episodes, podcasts, and tags:

npx tsx scripts/seed-local-data.ts

Reset everything and start fresh:

rm -rf .wrangler/state && npx tsx scripts/seed-local-data.ts

src/
├── index.ts                 # Hono app entry, cron handler, debug routes
├── types/index.ts           # All TypeScript interfaces
├── lib/
│   ├── constants.ts         # Tags, templates, error codes, timeouts
│   ├── kv.ts                # KV CRUD + activity log helpers
│   ├── url-parser.ts        # Apple Podcasts URL parsing
│   ├── audio.ts             # MP3 frame-aware chunking for large files
│   ├── styles.ts            # All CSS (embedded, Workers can't read files)
│   ├── job-status-do.ts     # Durable Object helpers + timeout detection
│   ├── monitor.ts           # Podcast monitoring logic
│   ├── discord.ts           # Discord webhook notifications
│   ├── turnstile.ts         # Spam protection verification
│   └── auth.ts              # JWT parsing, admin checks
├── services/
│   ├── apple-podcasts.ts    # Episode metadata lookup
│   ├── podcast-index.ts     # Podcast Index API client
│   ├── rss.ts               # RSS parsing + episode matching
│   ├── transcription.ts     # OpenAI gpt-4o-mini-transcribe
│   ├── summarization.ts     # GPT-5.4 summary generation
│   ├── tag-generation.ts    # GPT-5.4 tag generation
│   └── postmark.ts          # Postmark email for request form
├── routes/
│   ├── public.ts            # Public pages + request form
│   ├── api.ts               # JSON API (read-only)
│   └── admin.ts             # Admin dashboard + mutations
├── queue/
│   └── consumer.ts          # Background job processor
└── durable-objects/
    └── job-status.ts        # Job status DO for consistency

1. Admin submits (POST /admin/submit): Validates Apple Podcasts URL → checks cache → creates job → enqueues to Queue → redirects to dashboard
2. Queue Consumer (src/queue/consumer.ts): Background processing
   • Fetch episode metadata via Podcast Index + RSS
   • Check for existing transcript in RSS feed
   • Transcribe with OpenAI gpt-4o-mini-transcribe (chunking for >25MB)
   • Generate summary with GPT-5.4
   • Generate 2-3 tags with GPT-5.4 (non-critical)
   • Store in KV with 365-day TTL
   • Log to activity feed, notify Discord on failure
3. View (GET /episode/:id): Serve cached episode with summary
4. Monitoring (cron every 8h): Check monitored podcasts for new episodes, queue automatically

• Admin-only model: No public submission. One admin curates the archive. Visitors can request podcasts via a contact form.
• Durable Objects for job status: KV is eventually consistent; DOs provide strong consistency for real-time job tracking.
• Timeout detection: Jobs stuck >20 minutes are auto-marked as failed on home page render and in the cron handler.
• Podcast Index over iTunes API: iTunes returns 403s from Workers. Podcast Index is free and reliable.
• Embedded CSS: Workers can't read from filesystem. All styles live in src/lib/styles.ts.
• Non-critical tag generation: If tag generation fails, the job continues. Empty tags are acceptable.

Uses @cloudflare/vitest-pool-workers for a Workers-like test environment. 305+ tests.

npm test                      # Run all tests
npm test -- test/kv.test.ts   # Run single file

Note: Durable Object tests may show "Isolated storage" warnings. This is a vitest-pool-workers infrastructure issue, not a test failure.

# Set secrets (first time only)
wrangler secret put OPENAI_API_KEY
wrangler secret put PODCAST_INDEX_KEY
wrangler secret put PODCAST_INDEX_SECRET
wrangler secret put TURNSTILE_SECRET
wrangler secret put DISCORD_WEBHOOK_URL     # optional
wrangler secret put POSTMARK_API_KEY        # optional

# Deploy
npm run deploy

Create an Access application with two paths:

• tldl-pod.com/admin (exact)
• tldl-pod.com/admin/* (wildcard)

Policy: Allow only admin email addresses.

Available at /admin (protected by Cloudflare Access):

• AGENTS.md — Detailed architecture docs for AI coding agents
• docs/admin-pivot-plan.md — Design plan for the v2.0 admin-first pivot
• docs/ — Additional design documents and archived plans