# nvidia-ai-blueprints/pdf-to-podcast architecture

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

- Interactive diagram: https://gitdiagram.com/nvidia-ai-blueprints/pdf-to-podcast
- Repository: https://github.com/nvidia-ai-blueprints/pdf-to-podcast

## Overview

##### Project type and purpose
- This is a full-stack, microservice-based application (“PDF to Podcast”) that ingests PDFs, runs them through an LLM-driven agent to produce a transcript, and finally converts that transcript to speech.
- The README confirms it’s an NVIDIA AI Blueprint built on NIM microservices (LLM inference), Docling (PDF extraction), ElevenLabs (TTS), Redis, and MinIO.

##### File structure
- Top-level:
- frontend/ – CLI/demo code and shared Python SDK for talking to services
- services/ – four independent microservices, each in its own subfolder with Dockerfile
– APIService
– AgentService
– PDFService (with an embedded Docling “PDFModelService”)
– TTSService
- shared/ – common libraries replicated for services to share types, storage, connection logic
- workbench/ – Jupyter notebooks & compose for exploratory development
- configs: docker-compose.yaml, Makefile, CI workflows, tests, requirements.txt
- Patterns: API gateway → domain services → external engines; each service uses shared types and connection modules to communicate (HTTP + Redis).

##### Key architecture insights from the README
- Four microservices spin up via Docker Compose.
- Underlying 3 LLMs (via NIM endpoints) form an ensemble.
- Docling runs as a sub-service in PDFService (two Docker images: API + worker).
- Storage: MinIO for file artifacts, Redis for job queue/tracking.
- Tracing via Jaeger (optional).

a. Main layers (from top to bottom):
- Presentation Layer
- API Layer
- Domain (Orchestration) Layer
- Core Service Layer
- Infrastructure & External Dependencies Layer

b. Components per layer:
Presentation Layer (Layer 1)
– frontend/__main__.py CLI or demo UI
– workbench notebooks (optional interaction)

API Layer (Layer 2)
– APIService (FastAPI)
- Exposes Swagger at :8002
- Routes incoming jobs to the AgentService or PDFService

Domain (Orchestration) Layer (Layer 3)
– AgentService
- Coordinates transcript generation flows (uses shared API types, llmmanager)
– PDFService
- PDF ingestion & extraction sub-service (“PDFModelService”)
– TTSService
- Converts transcript text to audio via ElevenLabs
– Shared libraries (shared/shared & frontend/shared) supply common code for connection, job tracking, types

Core Service Layer (Layer 4)
– Docling (PDF extraction engine)
– NVIDIA NIM LLM endpoints (meta/llama-3.1 variants)
– ElevenLabs TTS API

Infrastructure & External Dependencies (Layer 5)
– Redis (job queue, rate limiting)
– MinIO (object storage for PDF, extracted text, audio artifacts)
– Docker Compose orchestration
– Jaeger (tracing)

1. Presentation → APIService (HTTP)
2. APIService → PDFService (HTTP) for ingestion, or → AgentService to start transcript
3. AgentService ↔ Core LLM endpoints (NIM) (HTTP/gRPC)
4. AgentService → Redis to enqueue/poll job status; → MinIO to fetch context PDFs
5. AgentService → TTSService (HTTP) passing transcript
6. TTSService ↔ ElevenLabs (HTTP) → generates audio → stores in MinIO
7. Presentation pulls final audio URL from MinIO via APIService

d. Architectural patterns & design principles:
- Microservice decomposition by business capability (PDF, Agent, TTS, API gateway)
- Shared library for type safety and DRY (in shared/ and frontend/shared/)
- Layered separation of concerns (UI vs routing vs orchestration vs engines vs infra)
- Polyglot persistence: Redis for transient state, MinIO for object storage
- Containerized deployment with Compose for dev/quickstart

e. Technologies & frameworks callouts:
- FastAPI (APIService, other services)
- Docker & Docker Compose
- Python (uv, ruff, pytest)
- NVIDIA NIM for inference
- Docling for PDF extraction
- ElevenLabs TTS
- Redis, MinIO, Jaeger

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Layer 1: Presentation Layer
  subgraph "Presentation Layer" 
    direction TB
    CLI["CLI / Demo UI"]:::ui
    Notebook["Workbench Notebook"]:::ui
  end

  %% Layer 2: API Layer
  subgraph "API Layer"
    direction TB
    APIService["APIService"]:::api
  end

  %% Layer 3: Domain (Orchestration) Layer
  subgraph "Domain Layer"
    direction TB
    AgentService["AgentService"]:::service
    PDFService["PDFService"]:::service
    PDFModelService["PDFModelService"]:::service
    TTSService["TTSService"]:::service
    SharedCode["Shared Libraries"]:::shared
  end

  %% Layer 4: Core Service Layer
  subgraph "Core Service Layer"
    direction TB
    Docling["Docling Engine"]:::core
    LLMs["NVIDIA NIM LLM Endpoints"]:::core
    ElevenLabs["ElevenLabs TTS API"]:::core
  end

  %% Layer 5: Infrastructure & External Dependencies
  subgraph "Infrastructure & External"
    direction TB
    Redis[(Redis)]:::infra
    MinIO[(MinIO)]:::infra
    Compose["Docker Compose"]:::infra
    Jaeger["Jaeger Tracing"]:::infra
  end

  %% Connections
  CLI -->|"HTTP"| APIService
  Notebook -->|"HTTP"| APIService
  APIService -->|"HTTP"| PDFService
  APIService -->|"HTTP"| AgentService
  AgentService -->|"gRPC/HTTP"| LLMs
  AgentService -->|"Redis pub/sub"| Redis
  AgentService -->|"S3 API"| MinIO
  AgentService -->|"HTTP"| TTSService
  PDFService -->|"invokes"| PDFModelService
  PDFModelService -->|"executes"| Docling
  TTSService -->|"HTTP"| ElevenLabs
  ElevenLabs -->|"stores audio"| MinIO
  CLI -->|"fetch audio URL"| MinIO
  APIService -->|"provides URL"| CLI

  %% Click Events
  click CLI "https://github.com/nvidia-ai-blueprints/pdf-to-podcast/blob/main/frontend/__main__.py"
  click Notebook "https://github.com/nvidia-ai-blueprints/pdf-to-podcast/blob/main/workbench/PDFtoPodcast.ipynb"
  click APIService "https://github.com/nvidia-ai-blueprints/pdf-to-podcast/blob/main/services/APIService/main.py"
  click APIService "https://github.com/nvidia-ai-blueprints/pdf-to-podcast/tree/main/services/APIService/Dockerfile"
  click AgentService "https://github.com/nvidia-ai-blueprints/pdf-to-podcast/blob/main/services/AgentService/main.py"
  click AgentService "https://github.com/nvidia-ai-blueprints/pdf-to-podcast/blob/main/services/AgentService/monologue_flow.py"
  click AgentService "https://github.com/nvidia-ai-blueprints/pdf-to-podcast/blob/main/services/AgentService/podcast_flow.py"
  click AgentService "https://github.com/nvidia-ai-blueprints/pdf-to-podcast/blob/main/services/AgentService/monologue_prompts.py"
  click AgentService "https://github.com/nvidia-ai-blueprints/pdf-to-podcast/blob/main/services/AgentService/podcast_prompts.py"
  click AgentService "https://github.com/nvidia-ai-blueprints/pdf-to-podcast/tree/main/services/AgentService/Dockerfile"
  click PDFService "https://github.com/nvidia-ai-blueprints/pdf-to-podcast/blob/main/services/PDFService/main.py"
  click PDFService "https://github.com/nvidia-ai-blueprints/pdf-to-podcast/tree/main/services/PDFService/Dockerfile"
  click PDFModelService "https://github.com/nvidia-ai-blueprints/pdf-to-podcast/tree/main/services/PDFService/PDFModelService/"
  click TTSService "https://github.com/nvidia-ai-blueprints/pdf-to-podcast/blob/main/services/TTSService/main.py"
  click TTSService "https://github.com/nvidia-ai-blueprints/pdf-to-podcast/tree/main/services/TTSService/Dockerfile"
  click SharedCode "https://github.com/nvidia-ai-blueprints/pdf-to-podcast/tree/main/shared/shared/"
  click SharedCode "https://github.com/nvidia-ai-blueprints/pdf-to-podcast/tree/main/frontend/shared/shared/"

  %% Styles
  classDef ui fill:#D0E6FF,stroke:#0366D6,color:#0366D6;
  classDef api fill:#BEE3F8,stroke:#3182CE,color:#3182CE;
  classDef service fill:#E6FFFA,stroke:#2C7A7B,color:#2C7A7B;
  classDef shared fill:#F0FFF4,stroke:#38A169,color:#38A169;
  classDef core fill:#FFF5E6,stroke:#DD6B20,color:#DD6B20;
  classDef infra fill:#EDF2F7,stroke:#4A5568,color:#4A5568;
```
