# naqashafzal/ai-content-studio architecture

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

- Interactive diagram: https://gitdiagram.com/naqashafzal/ai-content-studio
- Repository: https://github.com/naqashafzal/ai-content-studio

## Overview

#### 1. Purpose and entry points
Nullpk AI Content Studio is a local Python desktop application that turns a user topic into publishable YouTube-oriented media: research, script, narration, visuals, captions, metadata, and optional social uploads. The primary executable entry point is `main.py`; `run.sh` and `run.bat` are platform launch wrappers. The GUI is CustomTkinter-based.

Paths: `main.py`, `run.sh`, `run.bat`

#### 2. UI orchestration boundary
The desktop UI collects the topic, style, generation options, credentials/settings, and publishing choices. It initiates the pipeline and presents generated artifacts for review, especially SEO metadata and publishing actions. UI interaction should remain separated from long-running network/media work to preserve responsiveness.

Paths: `main.py`, `pipeline.py`, `config.py`

#### 3. Pipeline coordinator
`pipeline.py` is the lifecycle coordinator. It sequences conditional stages according to selected content format and options: research, script generation/revision, voice/audio, visual generation, assembly, captions, thumbnails, SEO, and upload. It is the main control-flow boundary between user intent and artifact production, and should own stage status, intermediate outputs, and failure propagation.

Paths: `pipeline.py`, `main.py`

#### 4. AI agents: research, writing, and content planning
`agents.py` contains the generative-AI roles that transform a topic and gathered context into research, scripts, fact-check/revision output, and likely SEO-oriented content. Gemini is the core text and TTS model family. Agent outputs become structured or textual inputs to downstream narration, visual selection, and metadata stages.

Paths: `agents.py`, `pipeline.py`, `api_clients.py`

#### 5. External API integration layer
`api_clients.py` centralizes calls to external providers: Google Gemini/Google Search grounding, Vertex AI image/video generation, NewsAPI headlines, and optional WaveSpeed video generation. This is the critical provider boundary for authentication, request/response normalization, retries, and service-specific failures.

Paths: `api_clients.py`, `config.py`, `agents.py`

#### 6. Media production and artifact assembly
The pipeline converts scripts into multi-speaker TTS/audio, optionally mixes background music, produces AI visuals, creates thumbnails, and renders the final video. FFmpeg is the essential local rendering dependency; Whisper generates speech timing and `pysubs2` supports styled ASS subtitles. `temp_preview.ass` is an example/generated subtitle-preview artifact, while `cyberpunk.json` is likely a visual/style preset consumed during generation.

Paths: `pipeline.py`, `temp_preview.ass`, `cyberpunk.json`

#### 7. Publishing and runtime dependencies
The final artifact path includes captioned video, thumbnail, SEO title/description/tags, chapter timestamps, and direct YouTube/Facebook publishing. YouTube requires local OAuth desktop credentials (`client_secrets.json`, user-provided); API keys and GCP project/location are persisted through the application configuration. Runtime requires Python 3.10+, FFmpeg on PATH, Google/Vertex credentials, and packages declared in `requirements.txt`.

Paths: `config.py`, `pipeline.py`, `requirements.txt`

Main entry points: [`pipeline.py`](https://github.com/naqashafzal/ai-content-studio/blob/main/pipeline.py) (Pipeline coordinator), [`main.py`](https://github.com/naqashafzal/ai-content-studio/blob/main/main.py) (CustomTkinter UI), [`api_clients.py`](https://github.com/naqashafzal/ai-content-studio/blob/main/api_clients.py) (Provider client layer), [`temp_preview.ass`](https://github.com/naqashafzal/ai-content-studio/blob/main/temp_preview.ass) (Captions & timing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop App"]
  node_launchers["Launch wrappers<br/>shell launchers<br/>[run.sh]"]
  node_main["Application entry<br/>Python entry point<br/>[main.py]"]
  node_ui["CustomTkinter UI<br/>desktop interface<br/>[main.py]"]
  node_config["Settings &amp; credentials<br/>configuration<br/>[config.py]"]
  node_runtime["Runtime dependencies<br/>environment manifest<br/>[requirements.txt]"]
end

subgraph group_ai["AI &amp; Providers"]
  node_agents["Research &amp; writing agents<br/>AI roles<br/>[agents.py]"]
  node_api_clients["Provider client layer<br/>API integration<br/>[api_clients.py]"]
  node_gemini(("Gemini &amp; Search grounding<br/>external AI service"))
  node_visual_providers(("Visual generation providers<br/>external AI services"))
  node_newsapi(("NewsAPI<br/>external news service"))
end

subgraph group_production["Media Production"]
  node_pipeline{{"Pipeline coordinator<br/>workflow orchestrator<br/>[pipeline.py]"}}
  node_audio["Narration &amp; audio mix<br/>media stage<br/>[pipeline.py]"]
  node_visuals["Visuals &amp; thumbnail<br/>media stage<br/>[pipeline.py]"]
  node_style_preset["Visual style preset<br/>generation preset<br/>[cyberpunk.json]"]
  node_render["Video rendering<br/>assembly stage<br/>[pipeline.py]"]
  node_captions["Captions &amp; timing<br/>subtitle stage<br/>[temp_preview.ass]"]
end

subgraph group_publishing["Publishing"]
  node_seo["SEO metadata &amp; chapters<br/>metadata stage<br/>[pipeline.py]"]
  node_publish["YouTube &amp; Facebook upload<br/>publishing stage<br/>[pipeline.py]"]
end

node_launchers -->|"starts"| node_main
node_main -->|"hosts"| node_ui
node_ui -->|"reads and saves settings"| node_config
node_ui -->|"submits generation request"| node_pipeline
node_config -->|"supplies credentials"| node_api_clients
node_pipeline -->|"runs research and writing"| node_agents
node_agents -->|"uses provider calls"| node_api_clients
node_api_clients -->|"text, grounding, TTS"| node_gemini
node_api_clients -->|"retrieves headlines"| node_newsapi
node_api_clients -->|"generates images or video"| node_visual_providers
node_pipeline -->|"creates narration"| node_audio
node_pipeline -->|"creates visual assets"| node_visuals
node_style_preset -->|"guides style"| node_visuals
node_audio -->|"audio track"| node_render
node_visuals -->|"visual assets"| node_render
node_pipeline -->|"generates subtitles"| node_captions
node_render -->|"video for alignment"| node_captions
node_captions -->|"captioned video"| node_publish
node_pipeline -->|"generates metadata"| node_seo
node_seo -->|"reviewable metadata"| node_ui
node_seo -->|"title, tags, chapters"| node_publish
node_ui -->|"publishing choice"| node_publish
node_runtime -.->|"runtime requirements"| node_main

click node_launchers "https://github.com/naqashafzal/ai-content-studio/blob/main/run.sh"
click node_main "https://github.com/naqashafzal/ai-content-studio/blob/main/main.py"
click node_ui "https://github.com/naqashafzal/ai-content-studio/blob/main/main.py"
click node_config "https://github.com/naqashafzal/ai-content-studio/blob/main/config.py"
click node_pipeline "https://github.com/naqashafzal/ai-content-studio/blob/main/pipeline.py"
click node_agents "https://github.com/naqashafzal/ai-content-studio/blob/main/agents.py"
click node_api_clients "https://github.com/naqashafzal/ai-content-studio/blob/main/api_clients.py"
click node_audio "https://github.com/naqashafzal/ai-content-studio/blob/main/pipeline.py"
click node_visuals "https://github.com/naqashafzal/ai-content-studio/blob/main/pipeline.py"
click node_style_preset "https://github.com/naqashafzal/ai-content-studio/blob/main/cyberpunk.json"
click node_render "https://github.com/naqashafzal/ai-content-studio/blob/main/pipeline.py"
click node_captions "https://github.com/naqashafzal/ai-content-studio/blob/main/temp_preview.ass"
click node_seo "https://github.com/naqashafzal/ai-content-studio/blob/main/pipeline.py"
click node_publish "https://github.com/naqashafzal/ai-content-studio/blob/main/pipeline.py"
click node_runtime "https://github.com/naqashafzal/ai-content-studio/blob/main/requirements.txt"

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_launchers,node_main,node_ui,node_config,node_runtime toneBlue
class node_agents,node_api_clients,node_gemini,node_visual_providers,node_newsapi toneAmber
class node_pipeline,node_audio,node_visuals,node_style_preset,node_render,node_captions toneMint
class node_seo,node_publish toneRose
```

## Components

### Desktop App

- [Launch wrappers](https://github.com/naqashafzal/ai-content-studio/blob/main/run.sh): shell launchers · Platform wrappers start the desktop app. · `run.sh`
- [Application entry](https://github.com/naqashafzal/ai-content-studio/blob/main/main.py): Python entry point · `main.py`
- [CustomTkinter UI](https://github.com/naqashafzal/ai-content-studio/blob/main/main.py): desktop interface · Collects options and presents artifacts for review. · `main.py`
- [Settings & credentials](https://github.com/naqashafzal/ai-content-studio/blob/main/config.py): configuration · Persists API keys, GCP project/location, and publishing settings. · `config.py`
- [Runtime dependencies](https://github.com/naqashafzal/ai-content-studio/blob/main/requirements.txt): environment manifest · Python packages plus local FFmpeg and cloud credentials are required. · `requirements.txt`

### AI & Providers

- [Research & writing agents](https://github.com/naqashafzal/ai-content-studio/blob/main/agents.py): AI roles · Creates research, scripts, revisions, and SEO-oriented content. · `agents.py`
- [Provider client layer](https://github.com/naqashafzal/ai-content-studio/blob/main/api_clients.py): API integration · Normalizes provider requests, retries, authentication, and failures. · `api_clients.py`
- **Gemini & Search grounding**: external AI service · Core text, research grounding, and TTS model family.
- **Visual generation providers**: external AI services · Vertex AI and optional WaveSpeed generate images or video.
- **NewsAPI**: external news service

### Media Production

- [Pipeline coordinator](https://github.com/naqashafzal/ai-content-studio/blob/main/pipeline.py): workflow orchestrator · Owns conditional stages, intermediate outputs, status, and failures. · `pipeline.py`
- [Narration & audio mix](https://github.com/naqashafzal/ai-content-studio/blob/main/pipeline.py): media stage · Generates multi-speaker speech and optional background music. · `pipeline.py`
- [Visuals & thumbnail](https://github.com/naqashafzal/ai-content-studio/blob/main/pipeline.py): media stage · Produces generation inputs, visuals, and thumbnails. · `pipeline.py`
- [Visual style preset](https://github.com/naqashafzal/ai-content-studio/blob/main/cyberpunk.json): generation preset · `cyberpunk.json`
- [Video rendering](https://github.com/naqashafzal/ai-content-studio/blob/main/pipeline.py): assembly stage · FFmpeg assembles audio and visuals into the final video. · `pipeline.py`
- [Captions & timing](https://github.com/naqashafzal/ai-content-studio/blob/main/temp_preview.ass): subtitle stage · Whisper timing and pysubs2 styling create captioned output. · `temp_preview.ass`

### Publishing

- [SEO metadata & chapters](https://github.com/naqashafzal/ai-content-studio/blob/main/pipeline.py): metadata stage · Produces title, description, tags, and chapter timestamps. · `pipeline.py`
- [YouTube & Facebook upload](https://github.com/naqashafzal/ai-content-studio/blob/main/pipeline.py): publishing stage · Publishes reviewed media; YouTube uses local OAuth credentials. · `pipeline.py`

## Connections

- Launch wrappers → Application entry: starts
- Application entry → CustomTkinter UI: hosts
- CustomTkinter UI → Settings & credentials: reads and saves settings
- CustomTkinter UI → Pipeline coordinator: submits generation request
- Settings & credentials → Provider client layer: supplies credentials
- Pipeline coordinator → Research & writing agents: runs research and writing
- Research & writing agents → Provider client layer: uses provider calls
- Provider client layer → Gemini & Search grounding: text, grounding, TTS
- Provider client layer → NewsAPI: retrieves headlines
- Provider client layer → Visual generation providers: generates images or video
- Pipeline coordinator → Narration & audio mix: creates narration
- Pipeline coordinator → Visuals & thumbnail: creates visual assets
- Visual style preset → Visuals & thumbnail: guides style
- Narration & audio mix → Video rendering: audio track
- Visuals & thumbnail → Video rendering: visual assets
- Pipeline coordinator → Captions & timing: generates subtitles
- Video rendering → Captions & timing: video for alignment
- Captions & timing → YouTube & Facebook upload: captioned video
- Pipeline coordinator → SEO metadata & chapters: generates metadata
- SEO metadata & chapters → CustomTkinter UI: reviewable metadata
- SEO metadata & chapters → YouTube & Facebook upload: title, tags, chapters
- CustomTkinter UI → YouTube & Facebook upload: publishing choice
- Runtime dependencies → Application entry: runtime requirements