# vamsi-krishna-b/ai-agents architecture

> Architecture diagram of the GitHub repository vamsi-krishna-b/ai-agents, 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/vamsi-krishna-b/ai-agents
- Repository: https://github.com/vamsi-krishna-b/ai-agents

## Overview

This is an autonomous YouTube channel manager. A user starts or monitors a job in the web UI; the API records it and dispatches background work, then the orchestrator runs research, scripting, media, voice, editing, thumbnail, and upload stages. The product also exposes approvals, scheduling, settings, analytics, and live logs. Source excerpts establish the main dispatch and orchestration links; some unsampled page and agent details are represented only where the README or source index supports them.

Main entry points: [`backend/agents/orchestrator.py`](https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/agents/orchestrator.py) (Pipeline orchestrator), [`frontend/src/api/client.ts`](https://github.com/vamsi-krishna-b/ai-agents/blob/main/frontend/src/api/client.ts) (HTTP API client), [`frontend/src/App.tsx`](https://github.com/vamsi-krishna-b/ai-agents/blob/main/frontend/src/App.tsx) (Web app routes), [`backend/main.py`](https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/main.py) (FastAPI and scheduler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web console"]
  node_app["Web app routes<br/>[App.tsx]"]
  node_dashboard["Dashboard<br/>[Dashboard.tsx]"]
  node_monitor["Pipeline monitor"]
  node_scriptui["Script editor<br/>[ScriptEditor.tsx]"]
  node_thumbnailui["Thumbnail page<br/>[Thumbnail.tsx]"]
  node_calendar["Calendar<br/>[Calendar.tsx]"]
  node_analyticsui["Analytics page<br/>[Analytics.tsx]"]
  node_settingsui["Settings page<br/>[Settings.tsx]"]
  node_client["HTTP API client<br/>[client.ts]"]
  node_ws["Live updates<br/>[useWebSocket.ts]"]
end

subgraph group_api["API and jobs"]
  node_api_main["FastAPI and scheduler<br/>[main.py]"]
  node_jobs["Job routes<br/>[jobs.py]"]
  node_settings["Settings routes<br/>[settings.py]"]
  node_analytics["Analytics routes<br/>[analytics.py]"]
  node_tasks["Celery pipeline tasks<br/>[pipeline_tasks.py]"]
end

subgraph group_pipeline["Content pipeline"]
  node_orchestrator["Pipeline orchestrator<br/>[orchestrator.py]"]
  node_research["Topic research<br/>[research_agent.py]"]
  node_script["Script generation<br/>[script_agent.py]"]
  node_media["Video clips<br/>[media_agent.py]"]
  node_voice["Voiceover<br/>[voice_agent.py]"]
  node_editor["Video editing<br/>[editor_agent.py]"]
  node_thumb["Thumbnail generation<br/>[thumbnail_agent.py]"]
  node_upload["YouTube upload<br/>[upload_agent.py]"]
end

subgraph group_providers["AI and publishing"]
  node_llm["Provider-aware text<br/>[llm.py]"]
  node_gemini["Gemini services<br/>[gemini.py]"]
  node_veo["Veo generation<br/>[veo.py]"]
  node_youtube["YouTube API<br/>[youtube.py]"]
end

subgraph group_state["Persistence"]
  node_mongo[("MongoDB collections<br/>[mongo.py]")]
end

node_user(("Channel manager"))
node_youtube_service(("YouTube"))
node_model_service(("Gemini / Groq / Veo"))

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_monitor
node_app -->|"routes to"| node_scriptui
node_app -->|"routes to"| node_thumbnailui
node_app -->|"routes to"| node_calendar
node_app -->|"routes to"| node_analyticsui
node_app -->|"routes to"| node_settingsui
node_dashboard -->|"calls"| node_client
node_monitor -->|"calls"| node_client
node_monitor -->|"subscribes"| node_ws
node_monitor -.->|"receives updates"| node_api_main
node_scriptui -->|"calls"| node_client
node_thumbnailui -->|"calls"| node_client
node_calendar -->|"calls"| node_client
node_analyticsui -->|"calls"| node_client
node_settingsui -->|"calls"| node_client
node_client -->|"requests jobs"| node_jobs
node_client -->|"requests settings"| node_settings
node_client -->|"requests analytics"| node_analytics
node_api_main -->|"mounts router"| node_jobs
node_api_main -->|"mounts router"| node_settings
node_api_main -->|"mounts router"| node_analytics
node_jobs -->|"creates jobs"| node_orchestrator
node_jobs -->|"dispatches"| node_tasks
node_jobs -->|"reads and writes"| node_mongo
node_settings -->|"reads and writes"| node_mongo
node_analytics -->|"reads and writes"| node_mongo
node_analytics -->|"fetches metrics"| node_youtube
node_tasks -->|"runs pipeline"| node_orchestrator
node_tasks -->|"connects and closes"| node_mongo
node_api_main -->|"schedules jobs"| node_orchestrator
node_api_main -->|"dispatches scheduled"| node_tasks
node_api_main -->|"manages connection"| node_mongo
node_orchestrator -->|"stores job state"| node_mongo
node_orchestrator -->|"runs stage"| node_research
node_orchestrator -->|"runs stage"| node_script
node_orchestrator -->|"runs stage"| node_media
node_orchestrator -->|"runs stage"| node_voice
node_orchestrator -->|"runs stage"| node_editor
node_orchestrator -->|"runs stage"| node_thumb
node_orchestrator -->|"runs stage"| node_upload
node_research -->|"generates topics"| node_llm
node_script -->|"generates script"| node_llm
node_media -->|"generates clips"| node_veo
node_voice -->|"generates audio"| node_gemini
node_thumb -->|"generates image"| node_gemini
node_upload -->|"uploads video"| node_youtube

click node_app "https://github.com/vamsi-krishna-b/ai-agents/blob/main/frontend/src/App.tsx"
click node_dashboard "https://github.com/vamsi-krishna-b/ai-agents/blob/main/frontend/src/pages/Dashboard.tsx"
click node_monitor "https://github.com/vamsi-krishna-b/ai-agents/blob/main/frontend/src/pages/PipelineMonitor.tsx"
click node_scriptui "https://github.com/vamsi-krishna-b/ai-agents/blob/main/frontend/src/pages/ScriptEditor.tsx"
click node_thumbnailui "https://github.com/vamsi-krishna-b/ai-agents/blob/main/frontend/src/pages/Thumbnail.tsx"
click node_calendar "https://github.com/vamsi-krishna-b/ai-agents/blob/main/frontend/src/pages/Calendar.tsx"
click node_analyticsui "https://github.com/vamsi-krishna-b/ai-agents/blob/main/frontend/src/pages/Analytics.tsx"
click node_settingsui "https://github.com/vamsi-krishna-b/ai-agents/blob/main/frontend/src/pages/Settings.tsx"
click node_client "https://github.com/vamsi-krishna-b/ai-agents/blob/main/frontend/src/api/client.ts"
click node_ws "https://github.com/vamsi-krishna-b/ai-agents/blob/main/frontend/src/hooks/useWebSocket.ts"
click node_api_main "https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/main.py"
click node_jobs "https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/api/jobs.py"
click node_settings "https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/api/settings.py"
click node_analytics "https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/api/analytics.py"
click node_tasks "https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/tasks/pipeline_tasks.py"
click node_orchestrator "https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/agents/orchestrator.py"
click node_research "https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/agents/research_agent.py"
click node_script "https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/agents/script_agent.py"
click node_media "https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/agents/media_agent.py"
click node_voice "https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/agents/voice_agent.py"
click node_editor "https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/agents/editor_agent.py"
click node_thumb "https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/agents/thumbnail_agent.py"
click node_upload "https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/agents/upload_agent.py"
click node_llm "https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/utils/llm.py"
click node_gemini "https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/utils/gemini.py"
click node_veo "https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/utils/veo.py"
click node_youtube "https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/utils/youtube.py"
click node_mongo "https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/db/mongo.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_app,node_dashboard,node_monitor,node_scriptui,node_thumbnailui,node_calendar,node_analyticsui,node_settingsui,node_client,node_ws toneBlue
class node_api_main,node_jobs,node_settings,node_analytics,node_tasks toneAmber
class node_orchestrator,node_research,node_script,node_media,node_voice,node_editor,node_thumb,node_upload toneMint
class node_llm,node_gemini,node_veo,node_youtube toneRose
class node_mongo,node_user,node_youtube_service,node_model_service toneIndigo
```

## Components

### Web console

- [Web app routes](https://github.com/vamsi-krishna-b/ai-agents/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Dashboard](https://github.com/vamsi-krishna-b/ai-agents/blob/main/frontend/src/pages/Dashboard.tsx): `frontend/src/pages/Dashboard.tsx`
- [Pipeline monitor](https://github.com/vamsi-krishna-b/ai-agents/blob/main/frontend/src/pages/PipelineMonitor.tsx): `frontend/src/pages/PipelineMonitor.tsx`
- [Script editor](https://github.com/vamsi-krishna-b/ai-agents/blob/main/frontend/src/pages/ScriptEditor.tsx): `frontend/src/pages/ScriptEditor.tsx`
- [Thumbnail page](https://github.com/vamsi-krishna-b/ai-agents/blob/main/frontend/src/pages/Thumbnail.tsx): `frontend/src/pages/Thumbnail.tsx`
- [Calendar](https://github.com/vamsi-krishna-b/ai-agents/blob/main/frontend/src/pages/Calendar.tsx): `frontend/src/pages/Calendar.tsx`
- [Analytics page](https://github.com/vamsi-krishna-b/ai-agents/blob/main/frontend/src/pages/Analytics.tsx): `frontend/src/pages/Analytics.tsx`
- [Settings page](https://github.com/vamsi-krishna-b/ai-agents/blob/main/frontend/src/pages/Settings.tsx): `frontend/src/pages/Settings.tsx`
- [HTTP API client](https://github.com/vamsi-krishna-b/ai-agents/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Live updates](https://github.com/vamsi-krishna-b/ai-agents/blob/main/frontend/src/hooks/useWebSocket.ts): `frontend/src/hooks/useWebSocket.ts`

### API and jobs

- [FastAPI and scheduler](https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/main.py): `backend/main.py`
- [Job routes](https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/api/jobs.py): `backend/api/jobs.py`
- [Settings routes](https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/api/settings.py): `backend/api/settings.py`
- [Analytics routes](https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/api/analytics.py): `backend/api/analytics.py`
- [Celery pipeline tasks](https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/tasks/pipeline_tasks.py): `backend/tasks/pipeline_tasks.py`

### Content pipeline

- [Pipeline orchestrator](https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/agents/orchestrator.py): `backend/agents/orchestrator.py`
- [Topic research](https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/agents/research_agent.py): `backend/agents/research_agent.py`
- [Script generation](https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/agents/script_agent.py): `backend/agents/script_agent.py`
- [Video clips](https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/agents/media_agent.py): `backend/agents/media_agent.py`
- [Voiceover](https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/agents/voice_agent.py): `backend/agents/voice_agent.py`
- [Video editing](https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/agents/editor_agent.py): `backend/agents/editor_agent.py`
- [Thumbnail generation](https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/agents/thumbnail_agent.py): `backend/agents/thumbnail_agent.py`
- [YouTube upload](https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/agents/upload_agent.py): `backend/agents/upload_agent.py`

### AI and publishing

- [Provider-aware text](https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/utils/llm.py): `backend/utils/llm.py`
- [Gemini services](https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/utils/gemini.py): `backend/utils/gemini.py`
- [Veo generation](https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/utils/veo.py): `backend/utils/veo.py`
- [YouTube API](https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/utils/youtube.py): `backend/utils/youtube.py`

### Persistence

- [MongoDB collections](https://github.com/vamsi-krishna-b/ai-agents/blob/main/backend/db/mongo.py): `backend/db/mongo.py`

### Other components

- **Channel manager**
- **YouTube**
- **Gemini / Groq / Veo**

## Connections

- Channel manager → Web app routes: uses (evidence: `frontend/src/App.tsx`)
- Web app routes → Dashboard: routes to (evidence: `frontend/src/App.tsx`)
- Web app routes → Pipeline monitor: routes to (evidence: `frontend/src/App.tsx`)
- Web app routes → Script editor: routes to (evidence: `frontend/src/App.tsx`)
- Web app routes → Thumbnail page: routes to (evidence: `frontend/src/App.tsx`)
- Web app routes → Calendar: routes to (evidence: `frontend/src/App.tsx`)
- Web app routes → Analytics page: routes to (evidence: `frontend/src/App.tsx`)
- Web app routes → Settings page: routes to (evidence: `frontend/src/App.tsx`)
- Dashboard → HTTP API client: calls (evidence: `frontend/src/pages/Dashboard.tsx`)
- Pipeline monitor → HTTP API client: calls (evidence: `frontend/src/pages/PipelineMonitor.tsx`)
- Pipeline monitor → Live updates: subscribes (evidence: `frontend/src/pages/PipelineMonitor.tsx`)
- Pipeline monitor → FastAPI and scheduler: receives updates
- Script editor → HTTP API client: calls (evidence: `frontend/src/pages/ScriptEditor.tsx`)
- Thumbnail page → HTTP API client: calls (evidence: `frontend/src/pages/Thumbnail.tsx`)
- Calendar → HTTP API client: calls (evidence: `frontend/src/pages/Calendar.tsx`)
- Analytics page → HTTP API client: calls (evidence: `frontend/src/pages/Analytics.tsx`)
- Settings page → HTTP API client: calls (evidence: `frontend/src/pages/Settings.tsx`)
- HTTP API client → Job routes: requests jobs (evidence: `frontend/src/api/client.ts`)
- HTTP API client → Settings routes: requests settings (evidence: `frontend/src/api/client.ts`)
- HTTP API client → Analytics routes: requests analytics (evidence: `frontend/src/api/client.ts`)
- FastAPI and scheduler → Job routes: mounts router (evidence: `backend/main.py`)
- FastAPI and scheduler → Settings routes: mounts router (evidence: `backend/main.py`)
- FastAPI and scheduler → Analytics routes: mounts router (evidence: `backend/main.py`)
- Job routes → Pipeline orchestrator: creates jobs (evidence: `backend/api/jobs.py`)
- Job routes → Celery pipeline tasks: dispatches (evidence: `backend/api/jobs.py`)
- Job routes → MongoDB collections: reads and writes (evidence: `backend/api/jobs.py`)
- Settings routes → MongoDB collections: reads and writes (evidence: `backend/api/settings.py`)
- Analytics routes → MongoDB collections: reads and writes (evidence: `backend/api/analytics.py`)
- Analytics routes → YouTube API: fetches metrics (evidence: `backend/api/analytics.py`)
- Celery pipeline tasks → Pipeline orchestrator: runs pipeline (evidence: `backend/tasks/pipeline_tasks.py`)
- Celery pipeline tasks → MongoDB collections: connects and closes (evidence: `backend/tasks/pipeline_tasks.py`)
- FastAPI and scheduler → Pipeline orchestrator: schedules jobs (evidence: `backend/main.py`)
- FastAPI and scheduler → Celery pipeline tasks: dispatches scheduled (evidence: `backend/main.py`)
- FastAPI and scheduler → MongoDB collections: manages connection (evidence: `backend/main.py`)
- Pipeline orchestrator → MongoDB collections: stores job state (evidence: `backend/agents/orchestrator.py`)
- Pipeline orchestrator → Topic research: runs stage (evidence: `backend/agents/orchestrator.py`)
- Pipeline orchestrator → Script generation: runs stage (evidence: `backend/agents/orchestrator.py`)
- Pipeline orchestrator → Video clips: runs stage (evidence: `backend/agents/orchestrator.py`)
- Pipeline orchestrator → Voiceover: runs stage (evidence: `backend/agents/orchestrator.py`)
- Pipeline orchestrator → Video editing: runs stage (evidence: `backend/agents/orchestrator.py`)
- Pipeline orchestrator → Thumbnail generation: runs stage (evidence: `backend/agents/orchestrator.py`)
- Pipeline orchestrator → YouTube upload: runs stage (evidence: `backend/agents/orchestrator.py`)
- Topic research → Provider-aware text: generates topics (evidence: `backend/agents/research_agent.py`)
- Script generation → Provider-aware text: generates script (evidence: `backend/agents/script_agent.py`)
- Video clips → Veo generation: generates clips (evidence: `backend/agents/media_agent.py`)
- Voiceover → Gemini services: generates audio (evidence: `backend/agents/voice_agent.py`)
- Thumbnail generation → Gemini services: generates image (evidence: `backend/agents/thumbnail_agent.py`)
- YouTube upload → YouTube API: uploads video (evidence: `backend/agents/upload_agent.py`)
