# apquinit/paper_to_podcast architecture

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

- Interactive diagram: https://gitdiagram.com/apquinit/paper_to_podcast
- Repository: https://github.com/apquinit/paper_to_podcast

## Overview

Key Components to Include:

##### Input Layer
- PDF Document Input Handler
- File System Storage for sample papers (/sample_papers)
- Environment Configuration (.env for API keys)

##### Core Processing Pipeline
a. Planning Chain
- PDF Text Extraction
- Section Analysis
- Content Planning Module

b. Discussion Chain
- Retrieval-Augmented Generation (RAG) System
- Multi-persona Dialogue Generator
- Content Verification Module

c. Enhancement Chain
- Script Refinement
- Transition Enhancement
- Quality Control

##### Text-to-Speech Layer
- OpenAI TTS API Integration
- Voice Synthesis for Three Personas
- Audio Output Generation

##### Output Layer
- Audio File Management
- Output Storage (/sample_podcasts)

##### Component Grouping
- Input Processing Group
- Core Pipeline Group
- Audio Generation Group
- Storage Group

##### Three-persona system
- Host
- Learner
- Expert

##### Integration Points
- OpenAI API calls
- File system interactions
- Future integration points for local LLMs and TTS

##### Future Roadmap Elements
A separate section showing planned improvements:
- Local LLM integration (Ollama)
- Open-source TTS integration
- Performance optimization points

Remember to add metrics and specifications:
- Average processing time
- Cost per conversion ($0.16 per 19-page paper)
- Output format specifications
- API usage metrics

This system design should clearly communicate both the current implementation and future scalability options, making it valuable for both development and planning purposes.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Define styles
    classDef input fill:#a8d1f0,stroke:#333
    classDef storage fill:#e0e0e0,stroke:#333
    classDef process fill:#90EE90,stroke:#333
    classDef api fill:#FFE5B4,stroke:#333
    classDef output fill:#DDA0DD,stroke:#333

    %% Input Layer
    subgraph InputLayer["Input Processing"]
        PDFInput["PDF Document Input"]:::input
        PDFStorage[("PDF Storage")]:::storage
        EnvConfig["Environment Config"]:::input
    end

    %% Core Processing Pipeline
    subgraph CorePipeline["Core Processing Pipeline"]
        subgraph PlanningChain["Planning Chain"]
            TextExtract["Text Extraction"]:::process
            SectionAnalysis["Section Analysis"]:::process
            ContentPlan["Content Planning"]:::process
        end

        subgraph DiscussionChain["Discussion Chain"]
            RAGSystem["RAG System"]:::process
            DialogueGen["Multi-persona Dialogue"]:::process
            ContentVerify["Content Verification"]:::process
        end

        subgraph EnhancementChain["Enhancement Chain"]
            ScriptRefine["Script Refinement"]:::process
            TransitionEnhance["Transition Enhancement"]:::process
            QualityControl["Quality Control"]:::process
        end
    end

    %% Text-to-Speech Layer
    subgraph TTSLayer["Text-to-Speech Layer"]
        OpenAITTS["OpenAI TTS API"]:::api
        VoiceSynth["Voice Synthesis"]:::process
        AudioGen["Audio Generation"]:::process
    end

    %% Output Layer
    subgraph OutputLayer["Output Processing"]
        AudioMgmt["Audio Management"]:::output
        PodcastStorage[("Podcast Storage")]:::storage
    end

    %% Connections
    PDFInput --> PDFStorage
    PDFStorage --> TextExtract
    EnvConfig -.-> OpenAITTS

    TextExtract --> SectionAnalysis
    SectionAnalysis --> ContentPlan
    ContentPlan --> RAGSystem
    RAGSystem --> DialogueGen
    DialogueGen --> ContentVerify
    ContentVerify --> ScriptRefine
    ScriptRefine --> TransitionEnhance
    TransitionEnhance --> QualityControl
    QualityControl --> VoiceSynth
    VoiceSynth --> AudioGen
    OpenAITTS -.-> AudioGen
    AudioGen --> AudioMgmt
    AudioMgmt --> PodcastStorage

    %% Click events for component mapping
    click PDFStorage "https://github.com/apquinit/paper_to_podcast/tree/main/sample_papers"
    click PDFInput "https://github.com/apquinit/paper_to_podcast/blob/main/paper_to_podcast.py"
    click ScriptRefine "https://github.com/apquinit/paper_to_podcast/blob/main/utils/script.py"
    click AudioGen "https://github.com/apquinit/paper_to_podcast/blob/main/utils/audio_gen.py"
    click PodcastStorage "https://github.com/apquinit/paper_to_podcast/tree/main/sample_podcasts"
    click DialogueGen "https://github.com/apquinit/paper_to_podcast/blob/main/templates.py"

    %% Legend
    subgraph Legend
        L1["Process"]:::process
        L2["Storage"]:::storage
        L3["API"]:::api
        L4["Input"]:::input
        L5["Output"]:::output
    end
```
