# vaishnavisukum/quilly architecture

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

- Interactive diagram: https://gitdiagram.com/vaishnavisukum/quilly
- Repository: https://github.com/vaishnavisukum/quilly

## Overview

Quilly turns a YouTube or plain-text transcript into normalized transcript JSON, then generates LinkedIn carousels, a newsletter, and FAQs as publishing-ready files. Users can invoke each step through the CLI or describe an action in natural language; the latter is routed through Gemini and dispatched by the router. Transcript handling also loads and caps inputs, while shared prompt/context and Gemini-client layers support routing and generation. Relationships are limited to calls and data flows shown in excerpts or README; output-file nodes represent artifacts, not inspected source modules.

Main entry points: [`src/quilly/router.py`](https://github.com/vaishnavisukum/quilly/blob/main/src/quilly/router.py) (Command router), [`src/quilly/generate.py`](https://github.com/vaishnavisukum/quilly/blob/main/src/quilly/generate.py) (Generation orchestration), [`src/quilly/cli.py`](https://github.com/vaishnavisukum/quilly/blob/main/src/quilly/cli.py) (CLI commands), [`src/quilly/client.py`](https://github.com/vaishnavisukum/quilly/blob/main/src/quilly/client.py) (Gemini client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["CLI and routing"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_router["Command router<br/>[router.py]"]
end

subgraph group_transcripts["Transcript handling"]
  node_fetch["YouTube fetch<br/>[transcript.py]"]
  node_text_import["Text conversion<br/>[transcript.py]"]
  node_transcript_load["Load and cap<br/>[transcript.py]"]
end

subgraph group_generation["Content generation"]
  node_router_prompt["Router prompt<br/>[prompts.py]"]
  node_generator["Generation orchestration<br/>[generate.py]"]
  node_prompts["Content prompts and context<br/>[prompts.py]"]
  node_carousel["Carousel generation<br/>[generate.py]"]
  node_newsletter["Newsletter generation<br/>[generate.py]"]
  node_faq["FAQ generation<br/>[generate.py]"]
end

subgraph group_integrations["External services"]
  node_client["Gemini client<br/>[client.py]"]
  node_gemini["Gemini API"]
  node_youtube["YouTube captions"]
end

node_user(("User"))
node_text_file["Plain-text transcript"]
node_transcript_file["Transcript JSON"]
node_assets["JSON and Markdown assets"]

node_user -->|"runs command"| node_cli
node_cli -->|"calls fetch"| node_fetch
node_cli -->|"calls conversion"| node_text_import
node_cli -->|"routes ask"| node_router
node_cli -->|"calls generation"| node_generator
node_router -->|"uses prompt"| node_router_prompt
node_router -->|"requests routing"| node_client
node_client -->|"calls model"| node_gemini
node_router -->|"dispatches fetch"| node_fetch
node_router -->|"dispatches conversion"| node_text_import
node_router -->|"dispatches generation"| node_generator
node_fetch -->|"fetches captions"| node_youtube
node_text_file -->|"provides text"| node_text_import
node_fetch -->|"writes entries"| node_transcript_file
node_text_import -->|"writes entries"| node_transcript_file
node_generator -->|"loads and caps"| node_transcript_load
node_transcript_load -->|"reads JSON"| node_transcript_file
node_generator -->|"generates type"| node_carousel
node_generator -->|"generates type"| node_newsletter
node_generator -->|"generates type"| node_faq
node_carousel -->|"uses prompt and context"| node_prompts
node_newsletter -->|"uses prompt and context"| node_prompts
node_faq -->|"uses prompt and context"| node_prompts
node_carousel -->|"requests generation"| node_client
node_newsletter -->|"requests generation"| node_client
node_faq -->|"requests generation"| node_client
node_carousel -->|"writes JSON and Markdown"| node_assets
node_newsletter -->|"writes Markdown"| node_assets
node_faq -->|"writes JSON and Markdown"| node_assets

click node_cli "https://github.com/vaishnavisukum/quilly/blob/main/src/quilly/cli.py"
click node_router "https://github.com/vaishnavisukum/quilly/blob/main/src/quilly/router.py"
click node_router_prompt "https://github.com/vaishnavisukum/quilly/blob/main/src/quilly/prompts.py"
click node_client "https://github.com/vaishnavisukum/quilly/blob/main/src/quilly/client.py"
click node_fetch "https://github.com/vaishnavisukum/quilly/blob/main/src/quilly/transcript.py"
click node_text_import "https://github.com/vaishnavisukum/quilly/blob/main/src/quilly/transcript.py"
click node_transcript_load "https://github.com/vaishnavisukum/quilly/blob/main/src/quilly/transcript.py"
click node_generator "https://github.com/vaishnavisukum/quilly/blob/main/src/quilly/generate.py"
click node_prompts "https://github.com/vaishnavisukum/quilly/blob/main/src/quilly/prompts.py"
click node_carousel "https://github.com/vaishnavisukum/quilly/blob/main/src/quilly/generate.py"
click node_newsletter "https://github.com/vaishnavisukum/quilly/blob/main/src/quilly/generate.py"
click node_faq "https://github.com/vaishnavisukum/quilly/blob/main/src/quilly/generate.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_cli,node_router,node_user toneBlue
class node_fetch,node_text_import,node_transcript_load toneAmber
class node_router_prompt,node_generator,node_prompts,node_carousel,node_newsletter,node_faq toneMint
class node_client,node_gemini,node_youtube toneRose
class node_text_file,node_transcript_file,node_assets toneIndigo
```

## Components

### CLI and routing

- [CLI commands](https://github.com/vaishnavisukum/quilly/blob/main/src/quilly/cli.py): `src/quilly/cli.py`
- [Command router](https://github.com/vaishnavisukum/quilly/blob/main/src/quilly/router.py): `src/quilly/router.py`

### Transcript handling

- [YouTube fetch](https://github.com/vaishnavisukum/quilly/blob/main/src/quilly/transcript.py): `src/quilly/transcript.py`
- [Text conversion](https://github.com/vaishnavisukum/quilly/blob/main/src/quilly/transcript.py): `src/quilly/transcript.py`
- [Load and cap](https://github.com/vaishnavisukum/quilly/blob/main/src/quilly/transcript.py): `src/quilly/transcript.py`

### Content generation

- [Router prompt](https://github.com/vaishnavisukum/quilly/blob/main/src/quilly/prompts.py): `src/quilly/prompts.py`
- [Generation orchestration](https://github.com/vaishnavisukum/quilly/blob/main/src/quilly/generate.py): `src/quilly/generate.py`
- [Content prompts and context](https://github.com/vaishnavisukum/quilly/blob/main/src/quilly/prompts.py): `src/quilly/prompts.py`
- [Carousel generation](https://github.com/vaishnavisukum/quilly/blob/main/src/quilly/generate.py): `src/quilly/generate.py`
- [Newsletter generation](https://github.com/vaishnavisukum/quilly/blob/main/src/quilly/generate.py): `src/quilly/generate.py`
- [FAQ generation](https://github.com/vaishnavisukum/quilly/blob/main/src/quilly/generate.py): `src/quilly/generate.py`

### External services

- [Gemini client](https://github.com/vaishnavisukum/quilly/blob/main/src/quilly/client.py): `src/quilly/client.py`
- **Gemini API**
- **YouTube captions**

### Other components

- **User**
- **Plain-text transcript**
- **Transcript JSON**
- **JSON and Markdown assets**

## Connections

- User → CLI commands: runs command (evidence: `README.md`)
- CLI commands → YouTube fetch: calls fetch (evidence: `src/quilly/cli.py`)
- CLI commands → Text conversion: calls conversion (evidence: `src/quilly/cli.py`)
- CLI commands → Command router: routes ask (evidence: `src/quilly/cli.py`)
- CLI commands → Generation orchestration: calls generation (evidence: `src/quilly/cli.py`)
- Command router → Router prompt: uses prompt (evidence: `src/quilly/router.py`)
- Command router → Gemini client: requests routing (evidence: `src/quilly/router.py`)
- Gemini client → Gemini API: calls model (evidence: `src/quilly/client.py`)
- Command router → YouTube fetch: dispatches fetch (evidence: `src/quilly/router.py`)
- Command router → Text conversion: dispatches conversion (evidence: `src/quilly/router.py`)
- Command router → Generation orchestration: dispatches generation (evidence: `src/quilly/router.py`)
- YouTube fetch → YouTube captions: fetches captions (evidence: `src/quilly/transcript.py`)
- Plain-text transcript → Text conversion: provides text (evidence: `README.md`)
- YouTube fetch → Transcript JSON: writes entries (evidence: `src/quilly/transcript.py`)
- Text conversion → Transcript JSON: writes entries (evidence: `src/quilly/transcript.py`)
- Generation orchestration → Load and cap: loads and caps (evidence: `src/quilly/generate.py`)
- Load and cap → Transcript JSON: reads JSON (evidence: `src/quilly/transcript.py`)
- Generation orchestration → Carousel generation: generates type (evidence: `src/quilly/generate.py`)
- Generation orchestration → Newsletter generation: generates type (evidence: `src/quilly/generate.py`)
- Generation orchestration → FAQ generation: generates type (evidence: `src/quilly/generate.py`)
- Carousel generation → Content prompts and context: uses prompt and context (evidence: `src/quilly/generate.py`)
- Newsletter generation → Content prompts and context: uses prompt and context (evidence: `src/quilly/generate.py`)
- FAQ generation → Content prompts and context: uses prompt and context (evidence: `src/quilly/generate.py`)
- Carousel generation → Gemini client: requests generation (evidence: `src/quilly/generate.py`)
- Newsletter generation → Gemini client: requests generation (evidence: `src/quilly/generate.py`)
- FAQ generation → Gemini client: requests generation (evidence: `src/quilly/generate.py`)
- Carousel generation → JSON and Markdown assets: writes JSON and Markdown (evidence: `src/quilly/generate.py`)
- Newsletter generation → JSON and Markdown assets: writes Markdown (evidence: `src/quilly/generate.py`)
- FAQ generation → JSON and Markdown assets: writes JSON and Markdown (evidence: `src/quilly/generate.py`)
