# saadings/podcastr architecture

> Architecture diagram of the GitHub repository saadings/podcastr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/saadings/podcastr
- Repository: https://github.com/saadings/podcastr

## Overview

##### Project type and purpose
- This is a full-stack SaaS web application (“AI Podcast Platform”) built with Next.js 13’s App Router.
- It lets authenticated users create, discover, and listen to AI-generated podcasts (text-to-speech + AI thumbnail generation) and persists data in a serverless Convex backend.

##### Main components
a. Frontend (Next.js App)
- App Router (src/app): handles routing, server components, and client components.
- React UI Components (src/components/ui, Carousel, PodcastCard, etc.)
- Context & Hooks (src/providers/*, src/hooks/*) for audio playback and Convex/Clerk integration
- Static Assets (public/*) served via Next’s built-in static file hosting / CDN

b. Authentication Service (Clerk)
- Clerk’s hosted auth UI (sign-in/sign-up)
- Clerk API for issuing JWTs and session management

c. Backend (Convex)
- Convex Server Functions (convex/*.ts) for handling business logic (podcast creation, user management, stats)
- Convex REST/HTTP endpoints (convex/http.ts)
- Schema & DataModel (convex/schema.ts, convex/_generated/dataModel.*)
- Convex Database (serverless NoSQL)

d. External AI Services (OpenAI)
- Text-to-speech API calls (convex/openAi.ts or direct fetch from frontend)
- Image generation API calls for thumbnails

e. Browser / Client
- Users interact via web browser on desktop/mobile

##### Relationships and Data Flow
1. User (Browser) → Next.js Frontend:
- Navigation between pages (discover, profile, create podcast)
- Click “Create Podcast” → fills form → triggers client-side hook (useGeneratePodcast)
2. Next.js → Convex Backend:
- Convex client (ConvexClerkProvider) issues queries/mutations to fetch podcasts, user profiles, etc.
- Convex HTTP functions invoked for custom endpoints
3. Convex Backend → Convex DB:
- Read/write podcast records, user records, listening stats
4. Convex Backend → OpenAI Services:
- Pass text prompt for TTS / image generation → receive audio blobs, images → store or proxy back to frontend
5. Next.js → Clerk Auth:
- Redirects to Clerk’s sign-in/sign-up flows → returns session tokens → stored client-side
6. Next.js → Static Assets:
- Serves mp3 assets and images from public/ via built-in asset pipeline

##### Architectural patterns & design principles
- Separation of concerns: UI layer (Next.js pages & components) vs business logic layer (Convex functions) vs persistence (Convex DB) vs external services (OpenAI, Clerk).
- Server components (data-fetching at server-side) vs client components (hooks, providers for interactive UI).
- Provider pattern: AudioProvider for playback state, ConvexClerkProvider for auth & data access.
- Atomic UI component structure (ui/ folder) for reusability.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Browser["Browser"]:::browser

    %% Frontend Layer
    subgraph "Next.js Frontend"
        direction TB
        AR["App Router"]:::frontend
        UI["UI Components"]:::frontend
        RC["React Components"]:::frontend
        AP["AudioProvider"]:::frontend
        CP["ConvexClerkProvider"]:::frontend
        GP["useGeneratePodcast Hook"]:::frontend
        MW["Middleware"]:::frontend
        UT["Utility Libraries"]:::frontend
        ST["Global Styles & Config"]:::frontend
        AS["Static Assets"]:::frontend
    end

    %% Backend Layer
    subgraph "Convex Backend"
        direction TB
        SF1["Server Function: podcasts.ts"]:::backend
        SF2["Server Function: users.ts"]:::backend
        HE["HTTP Endpoints"]:::backend
        OI["OpenAI Integration"]:::backend
        FH["File Storage Helpers"]:::backend
        SCH["Schema & DataModel"]:::backend
        GEN["Generated API Types"]:::backend
        DB["Convex Database"]:::database
    end

    %% External Services
    Clerk["Clerk Auth (Hosted UI)"]:::external
    ClerkConfig["Clerk Config"]:::external
    OpenAI["OpenAI API"]:::external

    %% Connections
    Browser -->|"navigate"| AR
    Browser -->|"load assets"| AS
    Browser -->|"auth UI"| Clerk
    AR -->|"routes to UI"| UI
    AR -->|"renders components"| RC
    AR -->|"wraps providers"| AP
    AR -->|"wraps providers"| CP
    RC -->|"uses hook"| GP
    AR -->|"middleware guard"| MW
    AP -->|"manages audio state"| RC
    CP -->|"auth & data client"| RC
    CP -->|"queries/mutations"| SF1
    CP -->|"queries/mutations"| SF2
    GP -->|"invoke generatePodcast"| SF1
    CP -->|"HTTP calls"| HE
    SF1 -->|"reads/writes"| DB
    SF2 -->|"reads/writes"| DB
    HE -->|"reads/writes"| DB
    SF1 -->|"calls"| OI
    SF2 -->|"calls"| OI
    OI -->|"requests TTS/images"| OpenAI
    OpenAI -->|"returns blobs"| SF1
    OpenAI -->|"returns blobs"| SF2
    AR -->|"serves static"| AS
    CP -->|"auth token"| Clerk
    Clerk -->|"JWT/session"| CP

    %% Click Events
    click AR "https://github.com/saadings/podcastr/tree/main/src/app"
    click UI "https://github.com/saadings/podcastr/tree/main/src/components/ui"
    click RC "https://github.com/saadings/podcastr/tree/main/src/components"
    click AP "https://github.com/saadings/podcastr/blob/main/src/providers/AudioProvider.tsx"
    click CP "https://github.com/saadings/podcastr/blob/main/src/providers/ConvexClerkProvider.tsx"
    click GP "https://github.com/saadings/podcastr/blob/main/src/hooks/useGeneratePodcast.ts"
    click AS "https://github.com/saadings/podcastr/tree/main/public"
    click MW "https://github.com/saadings/podcastr/blob/main/src/middleware.ts"
    click UT "https://github.com/saadings/podcastr/tree/main/src/lib"
    click ST "https://github.com/saadings/podcastr/blob/main/src/app/globals.css"
    click ST "https://github.com/saadings/podcastr/blob/main/tailwind.config.ts"
    click Clerk "https://github.com/saadings/podcastr/tree/main/src/app/(auth)"
    click ClerkConfig "https://github.com/saadings/podcastr/blob/main/convex/auth.config.ts"
    click SF1 "https://github.com/saadings/podcastr/blob/main/convex/podcasts.ts"
    click SF2 "https://github.com/saadings/podcastr/blob/main/convex/users.ts"
    click HE "https://github.com/saadings/podcastr/blob/main/convex/http.ts"
    click OI "https://github.com/saadings/podcastr/blob/main/convex/openAi.ts"
    click FH "https://github.com/saadings/podcastr/blob/main/convex/files.ts"
    click SCH "https://github.com/saadings/podcastr/blob/main/convex/schema.ts"
    click GEN "https://github.com/saadings/podcastr/blob/main/convex/_generated/api.d.ts"
    click GEN "https://github.com/saadings/podcastr/blob/main/convex/_generated/server.d.ts"

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef backend fill:#c8e6c9,stroke:#388e3c,color:#1b5e20
    classDef database fill:#c5cae9,stroke:#3f51b5,color:#1a237e
    classDef external fill:#ffe0b2,stroke:#f57c00,color:#e65100
    classDef browser fill:#e1bee7,stroke:#8e24aa,color:#4a148c
```
