Guides

These guides provide comprehensive documentation for features that span multiple components and services.

Available Guides

How to Add a New API Route

Canonical implementation pattern for new Hono routes:

• Required middleware chain order
• Permission patterns (requirePodcastRole, resolver-based checks, episode checks)
• Standard error response format
• Route mounting and test checklist

Components Covered:

• src/api/index.ts
• src/api/middleware/permissions.ts
• src/api/middleware/index.ts
• src/api/routes/

Booking Flow

Complete end-to-end documentation of the guest booking system:

• Guest submission process
• Host confirmation workflow
• Google Calendar event creation
• Email notifications (Resend)
• Automation integration

Components Covered:

• src/api/routes/bookings/
• src/lib/email/
• src/lib/google-calendar/
• src/lib/automation/

Guest Account Flow

Lifecycle of guest account creation, profile management, and account linking.

Podcast Lifecycle (Pause & Deletion)

Complete lifecycle management for podcasts: pausing, unpausing, and deletion workflows.

• Podcast status state machine (active → paused → pending_deletion)
• RSS feed behavior during each status (redirect logic, grace periods)
• Billing sync (Stripe pause/cancel based on podcast count)
• Scheduled cleanup (R2 storage, cache invalidation)
• Multi-step UI confirmation flow

Components Covered:

• src/api/routes/podcast-lifecycle.ts
• src/api/utils/stripe-sync.ts
• src/routes/(app)/p/[slug]/settings/+page.svelte
• src/lib/components/subscription/BillingWarning.svelte
• workers/lifecycle-manager/
• workers/rss-feed/ (status-aware query and redirect logic)
• supabase/migrations/20260413111213_add_podcast_lifecycle_states.sql

External-to-Internal Hosting Migration

Epic 11 — migrate an externally-hosted podcast onto show.fm while preserving subscriber GUID continuity:

• Per-episode external_guid / external_link_status state machine and auto-linker (external-episode-link queue)
• /p/[slug]/upgrade-hosting wizard (pre-flight + reconciliation + review + commit)
• Worker merge mode vs create mode in podcast-import-executor
• Cutover semantics (hosting_type flip on outcome='completed')
• Empty-feed fast path, drift guard, three lifecycle-manager watchdogs

Components Covered:

• src/api/routes/external-link/
• src/lib/external-link/
• src/routes/(app)/p/[slug]/upgrade-hosting/
• src/lib/components/external-link/
• workers/podcast-import-executor/src/external-link/
• workers/lifecycle-manager/src/index.ts (Epic 11 sweeps)
• supabase/migrations/20260428192931_…, 20260428202207_…, 20260429073542_…, 20260429073600_…, 20260507230120_…, 20260508093849_…

Guest Network Invitation Flow

End-to-end lifecycle of guest network invitations:

• Profile discovery and search
• Invitation creation with booking link selection
• Privacy enforcement (defense in depth across DB, API, and UI)
• Accept/decline flow with email notifications
• Booking URL construction and handoff to booking system

Components Covered:

• src/api/routes/guest-network/
• src/routes/(app)/guest-network/
• src/lib/types/profile.ts
• src/lib/email/templates/network-invitation.ts
• src/lib/email/templates/network-invitation-response.ts
• supabase/migrations/20260127000005_epic6d_guest_network.sql

Subscription Flow

End-to-end documentation of the subscription and payment system:

• Checkout session creation with user metadata
• Stripe webhook processing
• Profile update with subscription data
• Payment Link flow for unauthenticated users
• Integration test patterns

Components Covered:

• src/api/routes/stripe/
• src/api/routes/webhooks/stripe.ts
• src/lib/supabase/admin.ts
• src/api/routes/__tests__/subscription-flow.integration.test.ts