# rama-l7/telugu_podcast_agent architecture

> Architecture diagram of the GitHub repository rama-l7/telugu_podcast_agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rama-l7/telugu_podcast_agent
- Repository: https://github.com/rama-l7/telugu_podcast_agent

## Overview

Telugu Podcast Agent processes YouTube links from a Google Sheet: it validates and saves transcripts, then can generate a Telugu two-speaker script, synthesize audio, upload it to Drive, and update the sheet. The README identifies transcript processing as the completed default workflow and later stages as roadmap; the source index and excerpts also show full-pipeline and watcher components. Some implementation details are unsampled, so the graph omits uncertain relationships.

Main entry points: [`src/sheet_monitor.py`](https://github.com/rama-l7/telugu_podcast_agent/blob/master/src/sheet_monitor.py) (Sheet pipeline), [`src/transcript.py`](https://github.com/rama-l7/telugu_podcast_agent/blob/master/src/transcript.py) (Transcript extraction), [`src/drive_uploader.py`](https://github.com/rama-l7/telugu_podcast_agent/blob/master/src/drive_uploader.py) (Drive uploader), [`src/retry_utils.py`](https://github.com/rama-l7/telugu_podcast_agent/blob/master/src/retry_utils.py) (Retry and backoff)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Workflow orchestration"]
  node_main["CLI orchestrator<br/>[main.py]"]
  node_watcher["Polling watcher<br/>[watcher.py]"]
  node_monitor["Sheet pipeline<br/>[sheet_monitor.py]"]
end

subgraph group_content["Content processing"]
  node_transcript["Transcript extraction<br/>[transcript.py]"]
  node_script["Telugu script generation"]
  node_llm["LLM adapter<br/>[llm.py]"]
  node_tts["Speech synthesis<br/>[tts.py]"]
end

subgraph group_integrations["External integrations"]
  node_sheet[("Google Sheet")]
  node_transcript_files["Local transcripts"]
  node_youtube["YouTube captions"]
  node_llm_services["LLM providers"]
  node_audio["Local audio output"]
  node_drive["Drive uploader<br/>[drive_uploader.py]"]
  node_drive_service[("Google Drive")]
end

subgraph group_support["Shared runtime support"]
  node_retry["Retry and backoff<br/>[retry_utils.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
end

node_user(("Sheet operator"))

node_user -->|"enters links"| node_sheet
node_main -->|"runs pipeline"| node_monitor
node_main -->|"starts watch"| node_watcher
node_watcher -->|"runs pipeline"| node_monitor
node_monitor -->|"reads and updates"| node_sheet
node_monitor -->|"fetches and saves"| node_transcript
node_transcript -->|"fetches captions"| node_youtube
node_transcript -->|"writes transcripts"| node_transcript_files
node_monitor -->|"generates script"| node_script
node_script -->|"requests generation"| node_llm
node_llm -->|"calls provider"| node_llm_services
node_monitor -->|"synthesizes speech"| node_tts
node_tts -->|"writes audio"| node_audio
node_monitor -->|"uploads audio"| node_drive
node_drive -->|"uploads file"| node_drive_service
node_transcript -->|"uses retries"| node_retry
node_drive -->|"uses retries"| node_retry
node_retry -->|"reads retry settings"| node_config

click node_main "https://github.com/rama-l7/telugu_podcast_agent/blob/master/main.py"
click node_watcher "https://github.com/rama-l7/telugu_podcast_agent/blob/master/src/watcher.py"
click node_monitor "https://github.com/rama-l7/telugu_podcast_agent/blob/master/src/sheet_monitor.py"
click node_transcript "https://github.com/rama-l7/telugu_podcast_agent/blob/master/src/transcript.py"
click node_transcript_files "https://github.com/rama-l7/telugu_podcast_agent/tree/master/output/transcripts"
click node_script "https://github.com/rama-l7/telugu_podcast_agent/blob/master/src/script_generator.py"
click node_llm "https://github.com/rama-l7/telugu_podcast_agent/blob/master/src/llm.py"
click node_tts "https://github.com/rama-l7/telugu_podcast_agent/blob/master/src/tts.py"
click node_audio "https://github.com/rama-l7/telugu_podcast_agent/tree/master/output"
click node_drive "https://github.com/rama-l7/telugu_podcast_agent/blob/master/src/drive_uploader.py"
click node_retry "https://github.com/rama-l7/telugu_podcast_agent/blob/master/src/retry_utils.py"
click node_config "https://github.com/rama-l7/telugu_podcast_agent/blob/master/config.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_watcher,node_monitor toneBlue
class node_transcript,node_script,node_llm,node_tts toneAmber
class node_sheet,node_transcript_files,node_youtube,node_llm_services,node_audio,node_drive,node_drive_service toneMint
class node_retry,node_config toneRose
class node_user toneIndigo
```

## Components

### Workflow orchestration

- [CLI orchestrator](https://github.com/rama-l7/telugu_podcast_agent/blob/master/main.py): `main.py`
- [Polling watcher](https://github.com/rama-l7/telugu_podcast_agent/blob/master/src/watcher.py): `src/watcher.py`
- [Sheet pipeline](https://github.com/rama-l7/telugu_podcast_agent/blob/master/src/sheet_monitor.py): `src/sheet_monitor.py`

### Content processing

- [Transcript extraction](https://github.com/rama-l7/telugu_podcast_agent/blob/master/src/transcript.py): `src/transcript.py`
- [Telugu script generation](https://github.com/rama-l7/telugu_podcast_agent/blob/master/src/script_generator.py): `src/script_generator.py`
- [LLM adapter](https://github.com/rama-l7/telugu_podcast_agent/blob/master/src/llm.py): `src/llm.py`
- [Speech synthesis](https://github.com/rama-l7/telugu_podcast_agent/blob/master/src/tts.py): `src/tts.py`

### External integrations

- **Google Sheet**
- [Local transcripts](https://github.com/rama-l7/telugu_podcast_agent/tree/master/output/transcripts): `output/transcripts`
- **YouTube captions**
- **LLM providers**
- [Local audio output](https://github.com/rama-l7/telugu_podcast_agent/tree/master/output): `output`
- [Drive uploader](https://github.com/rama-l7/telugu_podcast_agent/blob/master/src/drive_uploader.py): `src/drive_uploader.py`
- **Google Drive**

### Shared runtime support

- [Retry and backoff](https://github.com/rama-l7/telugu_podcast_agent/blob/master/src/retry_utils.py): `src/retry_utils.py`
- [Runtime configuration](https://github.com/rama-l7/telugu_podcast_agent/blob/master/config.py): `config.py`

### Other components

- **Sheet operator**

## Connections

- Sheet operator → Google Sheet: enters links (evidence: `README.md`)
- CLI orchestrator → Sheet pipeline: runs pipeline (evidence: `main.py`)
- CLI orchestrator → Polling watcher: starts watch (evidence: `main.py`)
- Polling watcher → Sheet pipeline: runs pipeline (evidence: `src/watcher.py`)
- Sheet pipeline → Google Sheet: reads and updates (evidence: `README.md`)
- Sheet pipeline → Transcript extraction: fetches and saves (evidence: `src/sheet_monitor.py`)
- Transcript extraction → YouTube captions: fetches captions (evidence: `README.md`)
- Transcript extraction → Local transcripts: writes transcripts (evidence: `README.md`)
- Sheet pipeline → Telugu script generation: generates script (evidence: `src/sheet_monitor.py`)
- Telugu script generation → LLM adapter: requests generation (evidence: `src/script_generator.py`)
- LLM adapter → LLM providers: calls provider (evidence: `src/llm.py`)
- Sheet pipeline → Speech synthesis: synthesizes speech (evidence: `src/sheet_monitor.py`)
- Speech synthesis → Local audio output: writes audio (evidence: `README.md`)
- Sheet pipeline → Drive uploader: uploads audio (evidence: `README.md`)
- Drive uploader → Google Drive: uploads file (evidence: `src/drive_uploader.py`)
- Transcript extraction → Retry and backoff: uses retries (evidence: `src/transcript.py`)
- Drive uploader → Retry and backoff: uses retries (evidence: `src/drive_uploader.py`)
- Retry and backoff → Runtime configuration: reads retry settings (evidence: `src/retry_utils.py`)
