# fullfran/youtube2pdf architecture

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

- Interactive diagram: https://gitdiagram.com/fullfran/youtube2pdf
- Repository: https://github.com/fullfran/youtube2pdf

## Overview

##### Project Type and Purpose
- Type: Full-stack web application with a static front-end and Python-based API back-end.
- Purpose:
- Extract subtitles from YouTube videos
- Use AI (LLMs) to format them into structured Markdown
- Convert Markdown into PDF
- Serve results via a lightweight API and static UI

##### File Structure
Top-level files:
- Dockerfile, requirements.txt – container and dependencies
- README.md, privacyPolice.md – documentation
- index.html, style.css, script.js – static front-end assets
- main.py – FastAPI entry point
- subtitles.py – logic to fetch/parse YouTube subtitles
- sub2md.py – logic to convert raw subtitles into Markdown
- md2pdf.py – logic to render Markdown into PDF
Patterns:
- Separation of concerns: extraction → formatting → generation
- Single process Python backend exposing REST endpoints

##### README for Additional Insights
- Tech stack: FastAPI, LLMs (external AI service), Docker, Railway, GitHub Pages
- Deployment:
- Front-end on GitHub Pages (static hosting)
- Back-end container on Railway or local Docker
- Data flow described: URL → API → subtitles → AI formatting → Markdown/PDF → download

##### Main Components & Relationships
a. Front-end (Browser)
– index.html / style.css / script.js
– Hosted on GitHub Pages (CDN)
– User pastes YouTube URL, selects format, clicks “Generate”
– Makes HTTPS call (Fetch API) to Back-end API
b. API Layer (FastAPI)
– main.py (defines endpoints: /extract-markdown, /extract-pdf, etc.)
– Containerized via Dockerfile, deployed on Railway or any host
– Orchestrates internal modules
c. Subtitle Extraction Module
– subtitles.py
– Pulls captions via YouTube Data API or youtube-dl
d. Formatting Module
– sub2md.py
– Sends transcript to LLM (e.g. OpenAI) for structured Markdown
e. PDF Generation Module
– md2pdf.py
– Converts Markdown → PDF (e.g. using WeasyPrint, pandoc)
f. External Services
– YouTube (subtitle source)
– LLM API (AI formatting)

Data Flow:
1. Front-end → Back-end API (URL + format)
2. Back-end → subtitles.py → YouTube service
3. Raw subtitles → sub2md.py → LLM API
4. Markdown → md2pdf.py (if PDF) → binary PDF
5. Back-end → Front-end (Markdown or PDF response)

##### Architectural Patterns & Design Principles
- Micro-modular design: each Python script handles a single responsibility
- Stateless API endpoints for scalability
- Containerization for environment consistency
- Separation of front-end (static hosting) vs back-end (dynamic API)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Front-end Layer
    subgraph "Front-end (Static Hosting)" 
        direction TB
        FE_UI["Browser / GitHub Pages"]:::frontend
        FE_HTML["index.html"]:::frontend
        FE_CSS["style.css"]:::frontend
        FE_JS["script.js"]:::frontend
    end

    %% Back-end Layer
    subgraph "Back-end (FastAPI Container :8000)" 
        direction TB
        BE_Main["main.py\n(FastAPI)"]:::backend
        BE_Subtitles["subtitles.py\n(Subtitle Extractor)"]:::backend
        BE_Sub2MD["sub2md.py\n(Markdown Formatter)"]:::backend
        BE_MD2PDF["md2pdf.py\n(PDF Generator)"]:::backend
        BE_Reqs["requirements.txt"]:::backend
        BE_Docker["Dockerfile"]:::backend
    end

    %% External Services
    subgraph "External Services"
        direction TB
        EXT_YT["YouTube API"]:::external
        EXT_LLM["LLM Service (OpenAI API)"]:::external
    end

    %% Documentation
    DOCS["README.md\nprivacyPolice.md"]:::docs

    %% Connections: Front-end to Back-end
    FE_UI -->|HTTPS POST| BE_Main

    %% Main orchestration
    BE_Main -->|"extract_subtitles"| BE_Subtitles
    BE_Subtitles -->|Fetch captions| EXT_YT
    EXT_YT -->|Return subtitles| BE_Subtitles
    BE_Subtitles -->|Raw subtitles| BE_Sub2MD
    BE_Sub2MD -->|LLM request| EXT_LLM
    EXT_LLM -->|Structured Markdown| BE_Sub2MD
    BE_Sub2MD -->|Return Markdown| BE_Main
    BE_Main -->|Return Markdown| FE_UI

    %% PDF path
    BE_Main -->|Markdown| BE_MD2PDF
    BE_MD2PDF -->|Convert to PDF| BE_Main
    BE_Main -->|Return PDF| FE_UI

    %% Misc connections
    FE_UI --> DOCS
    BE_Main --> DOCS

    %% Click Events
    click FE_HTML "https://github.com/fullfran/youtube2pdf/blob/main/index.html"
    click FE_CSS "https://github.com/fullfran/youtube2pdf/blob/main/style.css"
    click FE_JS "https://github.com/fullfran/youtube2pdf/blob/main/script.js"
    click BE_Main "https://github.com/fullfran/youtube2pdf/blob/main/main.py"
    click BE_Subtitles "https://github.com/fullfran/youtube2pdf/blob/main/subtitles.py"
    click BE_Sub2MD "https://github.com/fullfran/youtube2pdf/blob/main/sub2md.py"
    click BE_MD2PDF "https://github.com/fullfran/youtube2pdf/blob/main/md2pdf.py"
    click BE_Reqs "https://github.com/fullfran/youtube2pdf/blob/main/requirements.txt"
    click BE_Docker "https://github.com/fullfran/youtube2pdf/tree/main/Dockerfile"
    click DOCS "https://github.com/fullfran/youtube2pdf/blob/main/README.md"
    click DOCS "https://github.com/fullfran/youtube2pdf/blob/main/privacyPolice.md"

    %% Styles
    classDef frontend fill:#f9f,stroke:#333,stroke-width:1px;
    classDef backend fill:#bbf,stroke:#333,stroke-width:1px;
    classDef external fill:#bfb,stroke:#333,stroke-width:1px;
    classDef docs fill:#ffd,stroke:#333,stroke-width:1px;
```
