# souvikg10/mystery-podcast-gen architecture

> Architecture diagram of the GitHub repository souvikg10/mystery-podcast-gen, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/souvikg10/mystery-podcast-gen
- Repository: https://github.com/souvikg10/mystery-podcast-gen

## Overview

##### Main Components
- Frontend (Client Side):
- Static HTML files (e.g., index.html, app.html, login.html)
- JavaScript files organized into folders like “auth”, “editor”, “projects”, and “ui” that drive dynamic interactions using HTMX, Tailwind CSS, and Vanilla JS.
- Backend (FastAPI Server):
- API endpoints located under the app/api directory with separate route files (auth, content, episodes, health, projects)
- Main entry point: app/main.py
- Configuration & Core:
- app/config for application settings, enabling environment-specific configurations.
- app/core for shared logic like exceptions and security mechanisms.
- Data Models and Database Integration:
- app/models contains definitions for authentication, content, and project representations.
- app/db contains database integration code (using Supabase).
- Services Layer (Business Logic):
- Divided by functionality:
· app/services/ai: Integrates with Google Gemini for content transformation.
· app/services/audio: Manages text-to-speech using OpenAI TTS.
· app/services/content: Handles content extraction and processing.
· app/services/storage: Manages file storage.
- Utilities:
- app/utils holds helper functions for miscellaneous tasks.

##### Relationships and Interactions
- The Frontend communicates with the Backend through RESTful API calls to endpoints defined in app/api/routes.
- The Backend handles incoming requests via FastAPI, where routing and dependency injection (from app/api/dependencies.py) manage request lifecycles.
- The Services layer receives calls from the API routes to perform operations: for instance, processing PDF content or generating podcast scripts using the AI integration.
- The Database component (via Supabase in app/db/supabase.py) is accessed for authentication, logging, and storage of user data and content metadata.
- Third-party integrations include:
- Google Gemini for advanced AI-powered content processing.
- OpenAI TTS for generating audio.
- External libraries like PyPDF2 and BeautifulSoup for PDF processing and web scraping.

##### Architectural Patterns and Design Principles
- Separation of Concerns:
- Different directories (api, models, services, config) indicate a layered architecture where each layer has a distinct responsibility.
- Modularization:
- Splitting functionality into separate service modules (AI, audio, content, storage) makes it easy to extend or modify parts of the system.
- API-driven Communication:
- The clear distinction between backend API endpoints (using FastAPI) and the frontend ensures a RESTful separation of responsibilities.

## Diagram (Mermaid)

```mermaid
flowchart TD

    subgraph "Frontend"
        FE1["Static HTML: index.html, app.html, login.html"]:::frontend
        FE2["JS HTMX/Tailwind: app.js, main.js"]:::frontend
        FE3["JS Auth: auth.js, password.js"]:::frontend
        FE4["JS Editor: audio.js, categories.js, transcript.js"]:::frontend
        FE5["JS Projects: episodes.js, projects.js"]:::frontend
        FE6["JS UI: modals.js, navigation.js, theme.js"]:::frontend
        FE7["JS Utilities: api.js, file-upload.js, helpers.js"]:::frontend
    end

    subgraph "Backend"
        BE1["FastAPI Main Entry: main.py"]:::backend

        subgraph "API Endpoints"
            API1["Auth Route: auth.py"]:::api
            API2["Content Route: content.py"]:::api
            API3["Episodes Route: episodes.py"]:::api
            API4["Health Route: health.py"]:::api
            API5["Projects Route: projects.py"]:::api
            API6["Dependencies: dependencies.py"]:::api
        end

        subgraph "Configuration & Core"
            CONFIG["Settings: settings.py"]:::backend
            CORE1["Core Exceptions: exceptions.py"]:::backend
            CORE2["Core Security: security.py"]:::backend
        end

        subgraph "Data Models"
            MODEL1["Auth Model: auth.py"]:::backend
            MODEL2["Content Model: content.py"]:::backend
            MODEL3["Project Model: project.py"]:::backend
        end

        subgraph "Services Layer"
            subgraph "AI Services"
                AI1["Gemini Integration: gemini.py"]:::backend
                AI2["Prompts: prompts.py"]:::backend
            end
            subgraph "Audio Services"
                AUDIO1["TTS: tts.py"]:::backend
            end
            subgraph "Content Services"
                CONTENT1["Extraction: extraction.py"]:::backend
                CONTENT2["Processing: processing.py"]:::backend
            end
            subgraph "Storage Services"
                STORAGE1["File Storage: file_storage.py"]:::backend
            end
        end

        subgraph "Backend Utilities"
            UTIL1["Helpers: helpers.py"]:::backend
        end
    end

    subgraph "Database & External Integrations"
        DB["Supabase (Database & Auth)"]:::database
        EXT1["Google Gemini API"]:::external
        EXT2["OpenAI TTS API"]:::external
    end

    %% Data Flow Connections
    FE1 -->|"API_call"| API1
    FE1 -->|"API_call"| API2
    FE1 -->|"API_call"| API3
    FE1 -->|"API_call"| API4
    FE1 -->|"API_call"| API5

    BE1 --> API1
    BE1 --> API2
    BE1 --> API3
    BE1 --> API4
    BE1 --> API5

    API1 -->|"triggers"| AI1
    API2 -->|"triggers"| CONTENT1
    API2 -->|"triggers"| CONTENT2
    API3 -->|"triggers"| AUDIO1
    API5 -->|"triggers"| STORAGE1

    AI1 -->|"integrates"| EXT1
    AUDIO1 -->|"integrates"| EXT2

    API1 ---|"DB_RW"| DB
    API2 ---|"DB_RW"| DB
    API3 ---|"DB_RW"| DB
    API5 ---|"DB_RW"| DB

    AI2 ---|"support"| AI1
    CONTENT1 ---|"flow"| CONTENT2

    %% Click Events for Frontend
    click FE1 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/static/index.html"
    click FE1 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/static/app.html"
    click FE1 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/static/login.html"
    click FE2 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/static/js/app.js"
    click FE2 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/static/js/main.js"
    click FE3 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/static/js/auth/auth.js"
    click FE3 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/static/js/auth/password.js"
    click FE4 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/static/js/editor/audio.js"
    click FE4 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/static/js/editor/categories.js"
    click FE4 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/static/js/editor/transcript.js"
    click FE5 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/static/js/projects/episodes.js"
    click FE5 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/static/js/projects/projects.js"
    click FE6 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/static/js/ui/modals.js"
    click FE6 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/static/js/ui/navigation.js"
    click FE6 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/static/js/ui/theme.js"
    click FE7 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/static/js/utils/api.js"
    click FE7 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/static/js/utils/file-upload.js"
    click FE7 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/static/js/utils/helpers.js"

    %% Click Events for Backend
    click BE1 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/app/main.py"
    click API1 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/app/api/routes/auth.py"
    click API2 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/app/api/routes/content.py"
    click API3 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/app/api/routes/episodes.py"
    click API4 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/app/api/routes/health.py"
    click API5 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/app/api/routes/projects.py"
    click API6 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/app/api/dependencies.py"
    click CONFIG "https://github.com/souvikg10/mystery-podcast-gen/blob/main/app/config/settings.py"
    click CORE1 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/app/core/exceptions.py"
    click CORE2 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/app/core/security.py"
    click MODEL1 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/app/models/auth.py"
    click MODEL2 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/app/models/content.py"
    click MODEL3 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/app/models/project.py"
    click AI1 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/app/services/ai/gemini.py"
    click AI2 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/app/services/ai/prompts.py"
    click AUDIO1 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/app/services/audio/tts.py"
    click CONTENT1 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/app/services/content/extraction.py"
    click CONTENT2 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/app/services/content/processing.py"
    click STORAGE1 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/app/services/storage/file_storage.py"
    click UTIL1 "https://github.com/souvikg10/mystery-podcast-gen/blob/main/app/utils/helpers.py"

    %% Styling Classes
    classDef frontend fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef backend fill:#D5F5E3,stroke:#196F3D,stroke-width:2px;
    classDef api fill:#FAD7A0,stroke:#D68910,stroke-width:2px;
    classDef database fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
```
