# leodabague/podcastfy architecture

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

- Interactive diagram: https://gitdiagram.com/leodabague/podcastfy
- Repository: https://github.com/leodabague/podcastfy

## Overview

##### Main components
- Client Interface: The package exposes a client (in podcastfy/client.py) which is used both in the provided Python notebook and CLI. This is the primary entry point for users.
- Content Parsing Subsystem: This is encapsulated in the content_parser package. It contains several modules that handle extraction from PDFs, websites, YouTube videos, and other input formats.
- Conversation/Content Generation: This is the core logic that “conversationalizes” content, blending multi-modal inputs into podcast dialogues.
- Text-to-Speech (TTS) Module: Found in podcastfy/tts and its related providers, these modules integrate multiple advanced TTS engines (Edge, ElevenLabs, Gemini, etc.) to convert text into speech.
- Configuration & Utilities: This includes config.yaml, conversation_config, and helper modules under podcastfy/utils that manage settings, logging, and flow control.
- Data & Temporary Storage: Directories such as data/, podcastfy/data/ and tests/data illustrate how input audio, transcripts, PDFs, and images are stored and processed.

##### Relationships and Data Flow
- The Client Interface accepts requests (via Python or CLI) which include URLs, PDF paths, or other content identifiers.
- These requests flow into the Content Parsing Subsystem, where different “extractors” (website_extractor, pdf_extractor, youtube_transcriber, etc.) transform raw sources into text.
- The extracted text is passed to the Content Generation module where GenAI models (both remote and local as enabled by configuration) generate conversational content.
- The generated conversation is then fed into the Text-to-Speech module, which selects a provider (based on configuration) to output audio.
- Processed audio and related outputs (transcripts, temporary files) are stored in the appropriate data directories.
- Additionally, configuration files (e.g., podcastfy/config.yaml) and utility modules support logging and error handling across the flow.

##### Architectural Patterns and Design Principles
- Modular Design: Each functional area (extraction, generation, TTS) is isolated into its own module/subsystem.
- Extensibility: The design supports multiple TTS providers and can be extended to support additional input formats.
- Configurability: The use of configuration files and environment-specific settings (including Dockerfiles, docker-compose.yml) enables flexible deployment.
- Pipeline/Workflow: There is a sequential processing pipeline – starting with input acquisition, through parsing and AI content generation, and finally audio synthesis.

- Use clear labels for each module (Client, Content Parser(s), Content Generator, TTS Provider, Data Storage).
- Optionally, include configuration and deployment management blocks that show the application’s readiness for Dockerization and CI/CD integration (as seen in .github/workflows and Dockerfiles).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Main Pipeline
    CI["Client Interface"]:::client
    CP["Content Parsing Subsystem"]:::parser

    subgraph "Content Parsers"
        CP1["content_extractor.py"]:::parser
        CP2["pdf_extractor.py"]:::parser
        CP3["website_extractor.py"]:::parser
        CP4["youtube_transcriber.py"]:::parser
    end

    subgraph "Conversation Engine"
        CG2["Conversation Config"]:::generator
        CG1["Content Generator"]:::generator
        CG2 -->|"configures"| CG1
    end

    subgraph "TTS Module"
        TTS1["TTS Module"]:::tts
        TTS_base["base.py"]:::tts
        TTS_factory["factory.py"]:::tts
        TTS2["edge.py"]:::tts
        TTS3["elevenlabs.py"]:::tts
        TTS4["gemini.py"]:::tts
        TTS5["geminimulti.py"]:::tts
        TTS6["openai.py"]:::tts
        TTS1 --> TTS_base
        TTS_base --> TTS_factory
        TTS_factory --> TTS2
        TTS2 --> TTS3
        TTS3 --> TTS4
        TTS4 --> TTS5
        TTS5 --> TTS6
    end

    subgraph "Data Storage"
        DS1["Data Directory"]:::storage
        DS2["Podcast Data"]:::storage
        DS1 --> DS2
    end

    subgraph "Configuration & Utilities"
        CU1["Config File"]:::config
        CU2["Utilities"]:::config
    end

    subgraph "Deployment"
        D1["Dockerfile"]:::deploy
        D2["Dockerfile.dev"]:::deploy
        D3["docker-compose.yml"]:::deploy
        D4["Makefile"]:::deploy
        D1 --> D2
        D2 --> D3
        D3 --> D4
    end

    ES["External Services (GenAI & TTS)"]:::external

    %% Flow Connections
    CI -->|"sends"| CP
    CP -->|"initiates"| CP1
    CP1 -->|"parses"| CP2
    CP2 -->|"parses"| CP3
    CP3 -->|"parses"| CP4
    CP4 -->|"aggregates"| CG2
    CG1 -->|"generates"| TTS1
    TTS6 -->|"outputs audio"| DS1

    %% Configuration & Utilities support
    CU1 -->|"supports"| CP
    CU2 -->|"supports"| CG1
    CU2 -->|"supports"| TTS1

    %% External Services integration
    CG1 -->|"calls"| ES
    TTS1 -->|"integrates"| ES

    %% Transition within pipeline
    CG2 --> CG1

    %% Click Events
    click CI "https://github.com/leodabague/podcastfy/blob/main/podcastfy/client.py"
    click CP "https://github.com/leodabague/podcastfy/tree/main/podcastfy/content_parser"
    click CP1 "https://github.com/leodabague/podcastfy/blob/main/podcastfy/content_parser/content_extractor.py"
    click CP2 "https://github.com/leodabague/podcastfy/blob/main/podcastfy/content_parser/pdf_extractor.py"
    click CP3 "https://github.com/leodabague/podcastfy/blob/main/podcastfy/content_parser/website_extractor.py"
    click CP4 "https://github.com/leodabague/podcastfy/blob/main/podcastfy/content_parser/youtube_transcriber.py"
    click CG1 "https://github.com/leodabague/podcastfy/blob/main/podcastfy/content_generator.py"
    click CG2 "https://github.com/leodabague/podcastfy/blob/main/podcastfy/conversation_config.yaml"
    click TTS1 "https://github.com/leodabague/podcastfy/tree/main/podcastfy/tts"
    click TTS_base "https://github.com/leodabague/podcastfy/blob/main/podcastfy/tts/base.py"
    click TTS_factory "https://github.com/leodabague/podcastfy/blob/main/podcastfy/tts/factory.py"
    click TTS2 "https://github.com/leodabague/podcastfy/blob/main/podcastfy/tts/edge.py"
    click TTS3 "https://github.com/leodabague/podcastfy/blob/main/podcastfy/tts/elevenlabs.py"
    click TTS4 "https://github.com/leodabague/podcastfy/blob/main/podcastfy/tts/gemini.py"
    click TTS5 "https://github.com/leodabague/podcastfy/blob/main/podcastfy/tts/geminimulti.py"
    click TTS6 "https://github.com/leodabague/podcastfy/blob/main/podcastfy/tts/openai.py"
    click CU1 "https://github.com/leodabague/podcastfy/blob/main/podcastfy/config.yaml"
    click CU2 "https://github.com/leodabague/podcastfy/tree/main/podcastfy/utils"
    click DS1 "https://github.com/leodabague/podcastfy/tree/main/data/"
    click DS2 "https://github.com/leodabague/podcastfy/tree/main/podcastfy/data"
    click D1 "https://github.com/leodabague/podcastfy/tree/main/Dockerfile"
    click D2 "https://github.com/leodabague/podcastfy/blob/main/Dockerfile.dev"
    click D3 "https://github.com/leodabague/podcastfy/blob/main/docker-compose.yml"
    click D4 "https://github.com/leodabague/podcastfy/tree/main/Makefile"

    %% Styles
    classDef client fill:#add8e6,stroke:#0000FF,stroke-width:2px;
    classDef parser fill:#98FB98,stroke:#008000,stroke-width:2px;
    classDef generator fill:#FFD700,stroke:#DAA520,stroke-width:2px;
    classDef tts fill:#DDA0DD,stroke:#800080,stroke-width:2px;
    classDef config fill:#AFEEEE,stroke:#4682B4,stroke-width:2px;
    classDef storage fill:#90EE90,stroke:#006400,stroke-width:2px;
    classDef deploy fill:#D3D3D3,stroke:#A9A9A9,stroke-width:2px;
    classDef external fill:#FFB6C1,stroke:#FF69B4,stroke-width:2px;
```
