1 files changed, 43 insertions, 0 deletions
diff --git a/Biz/PodcastItLater/DESIGN.md b/Biz/PodcastItLater/DESIGN.md
new file mode 100644
index 0000000..29c4837
--- /dev/null
+++ b/Biz/PodcastItLater/DESIGN.md
@@ -0,0 +1,43 @@
+# 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.