# PodcastItLater Design & Architecture

## Overview
Service converting web articles to podcast episodes via email/web submission.

## Architecture
- **Web**: `Biz/PodcastItLater/Web.py` (Ludic + HTMX + Starlette)
- **Worker**: `Biz/PodcastItLater/Worker.py` (Background processing)
- **Core**: `Biz/PodcastItLater/Core.py` (DB & Shared Logic)
- **Billing**: `Biz/PodcastItLater/Billing.py` (Stripe Integration)

## Key Features
1.  **User Management**: Email-based magic links, RSS tokens.
2.  **Article Processing**: Trafilatura extraction -> LLM cleanup -> TTS.
3.  **Billing (In Progress)**: Stripe Checkout/Portal, Freemium model.

## Path to Paid Product (Epic: t-143KQl2)

### 1. Billing Infrastructure
- **Stripe**: Use Stripe Checkout for subs, Portal for management.
- **Webhooks**: Handle `checkout.session.completed`, `customer.subscription.*`.
- **Tiers**:
    - `Free`: 10 articles/month.
    - `Paid`: Unlimited (initially).

### 2. Usage Tracking
- **Table**: `users` table needs `plan_tier`, `subscription_status`, `stripe_customer_id`.
- **Logic**: Check usage count vs tier limit before allowing submission.
- **Reset**: Usage counters reset at billing period boundary.

### 3. Admin Dashboard
- View all users and their status.
- Manually retry/delete jobs.
- View metrics (signups, conversions).

## UX Polish (Epic: t-1vIPJYG)
- **Mobile**: Ensure all pages work on mobile.
- **Feedback**: Better error messages for failed URLs.
- **Navigation**: Clean up navbar, account management access.

## Audio Improvements
- **Intro/Outro**: Add metadata-rich intro ("Title by Author").
- **Sound Design**: Crossfade intro music.