# darkzogx/youtube-automation-agent architecture

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

- Interactive diagram: https://gitdiagram.com/darkzogx/youtube-automation-agent
- Repository: https://github.com/darkzogx/youtube-automation-agent

## Overview

YouTube Automation Agent is a self-hosted system that researches channel topics, creates and assembles videos, holds them for human review, publishes approved content, and learns from channel outcomes. The local dashboard and server form the operator entry point; documented features also include scene repair, Shorts, discoverability checks, audience engagement, and controlled growth experiments. The map preserves these branches, but several are represented by their directory because their implementation was not excerpted. Relationships use README workflow statements or SOURCE INDEX references; unsampled wiring is not inferred.

Main entry points: [`index.js`](https://github.com/darkzogx/youtube-automation-agent/blob/master/index.js) (Application server), [`agents/content-strategy-agent.js`](https://github.com/darkzogx/youtube-automation-agent/blob/master/agents/content-strategy-agent.js) (Topic strategy), [`agents/script-writer-agent.js`](https://github.com/darkzogx/youtube-automation-agent/blob/master/agents/script-writer-agent.js) (Script writer), [`utils/channel-learning-engine.js`](https://github.com/darkzogx/youtube-automation-agent/blob/master/utils/channel-learning-engine.js) (Channel learning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_console["Operator console"]
  node_dashboard["Dashboard<br/>[app.js]"]
  node_server["Application server<br/>[index.js]"]
  node_database[("Channel database<br/>[db.js]")]
  node_operator_service["Operator controls"]
end

subgraph group_planning["Planning and writing"]
  node_strategy["Topic strategy"]
  node_autonomous["Channel operator"]
  node_script["Script writer"]
  node_text["Text generation<br/>[ai-text-service.js]"]
  node_seo["SEO metadata"]
end

subgraph group_production["Video production"]
  node_production["Production manager"]
  node_video["Video generation"]
  node_media["Media provider routing"]
  node_providers["Video providers<br/>[video-providers.js]"]
  node_scene["Scene repair"]
  node_shorts["Shorts repurposing"]
end

subgraph group_publishing["Review and publishing"]
  node_review["Human approval<br/>[index.js]"]
  node_publishing["Publishing scheduler"]
  node_discoverability["Discoverability checks"]
end

subgraph group_learning["Learning and growth"]
  node_engagement["Audience engagement"]
  node_analytics["Analytics optimizer"]
  node_learning["Channel learning"]
  node_retention["Scene retention"]
  node_experiments["Growth experiments"]
end

node_operator(("Channel owner"))
node_youtube["YouTube"]

node_operator -->|"operates"| node_dashboard
node_dashboard -->|"requests"| node_server
node_server -->|"reads and writes"| node_database
node_server -->|"initializes"| node_strategy
node_server -->|"initializes"| node_script
node_server -->|"runs jobs"| node_production
node_server -->|"routes publishing"| node_publishing
node_server -->|"routes operator"| node_autonomous
node_server -->|"uses controls"| node_operator_service
node_autonomous -->|"plans topics"| node_strategy
node_strategy -->|"generates strategy"| node_text
node_script -->|"generates scripts"| node_text
node_strategy -.->|"feeds production"| node_script
node_script -.->|"creates metadata"| node_seo
node_production -->|"generates media"| node_video
node_video -->|"requests clips"| node_media
node_media -->|"routes generation"| node_providers
node_production -->|"enables repair"| node_scene
node_operator -->|"reviews content"| node_review
node_review -->|"approves scheduling"| node_publishing
node_publishing -->|"uploads approved"| node_youtube
node_review -.->|"runs preflight"| node_discoverability
node_review -.->|"repurposes approved"| node_shorts
node_youtube -.->|"provides outcomes"| node_analytics
node_analytics -->|"proposes lessons"| node_learning
node_learning -->|"analyzes scenes"| node_retention
node_learning -.->|"informs tests"| node_experiments
node_operator -->|"approves lessons"| node_learning
node_youtube -.->|"supplies comments"| node_engagement
node_engagement -.->|"presents reply drafts"| node_operator

click node_dashboard "https://github.com/darkzogx/youtube-automation-agent/blob/master/dashboard/app.js"
click node_server "https://github.com/darkzogx/youtube-automation-agent/blob/master/index.js"
click node_database "https://github.com/darkzogx/youtube-automation-agent/blob/master/database/db.js"
click node_strategy "https://github.com/darkzogx/youtube-automation-agent/blob/master/agents/content-strategy-agent.js"
click node_autonomous "https://github.com/darkzogx/youtube-automation-agent/blob/master/utils/autonomous-channel-operator.js"
click node_script "https://github.com/darkzogx/youtube-automation-agent/blob/master/agents/script-writer-agent.js"
click node_text "https://github.com/darkzogx/youtube-automation-agent/blob/master/utils/ai-text-service.js"
click node_seo "https://github.com/darkzogx/youtube-automation-agent/blob/master/agents/seo-optimizer-agent.js"
click node_production "https://github.com/darkzogx/youtube-automation-agent/blob/master/agents/production-management-agent.js"
click node_video "https://github.com/darkzogx/youtube-automation-agent/blob/master/utils/ai-video-generator.js"
click node_media "https://github.com/darkzogx/youtube-automation-agent/blob/master/utils/media-generation-service.js"
click node_providers "https://github.com/darkzogx/youtube-automation-agent/blob/master/utils/video-providers.js"
click node_scene "https://github.com/darkzogx/youtube-automation-agent/blob/master/utils/scene-repair-service.js"
click node_shorts "https://github.com/darkzogx/youtube-automation-agent/blob/master/utils/shorts-repurposing-service.js"
click node_review "https://github.com/darkzogx/youtube-automation-agent/blob/master/index.js"
click node_publishing "https://github.com/darkzogx/youtube-automation-agent/blob/master/agents/publishing-scheduling-agent.js"
click node_discoverability "https://github.com/darkzogx/youtube-automation-agent/blob/master/utils/discoverability-service.js"
click node_engagement "https://github.com/darkzogx/youtube-automation-agent/blob/master/utils/audience-engagement-service.js"
click node_analytics "https://github.com/darkzogx/youtube-automation-agent/blob/master/agents/analytics-optimization-agent.js"
click node_learning "https://github.com/darkzogx/youtube-automation-agent/blob/master/utils/channel-learning-engine.js"
click node_retention "https://github.com/darkzogx/youtube-automation-agent/blob/master/utils/scene-retention-engine.js"
click node_experiments "https://github.com/darkzogx/youtube-automation-agent/blob/master/utils/growth-experiment-service.js"
click node_operator_service "https://github.com/darkzogx/youtube-automation-agent/blob/master/utils/operator-service.js"

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_dashboard,node_server,node_database,node_operator_service toneBlue
class node_strategy,node_autonomous,node_script,node_text,node_seo toneAmber
class node_production,node_video,node_media,node_providers,node_scene,node_shorts toneMint
class node_review,node_publishing,node_discoverability toneRose
class node_engagement,node_analytics,node_learning,node_retention,node_experiments,node_operator,node_youtube toneIndigo
```

## Components

### Operator console

- [Dashboard](https://github.com/darkzogx/youtube-automation-agent/blob/master/dashboard/app.js): `dashboard/app.js`
- [Application server](https://github.com/darkzogx/youtube-automation-agent/blob/master/index.js): `index.js`
- [Channel database](https://github.com/darkzogx/youtube-automation-agent/blob/master/database/db.js): `database/db.js`
- [Operator controls](https://github.com/darkzogx/youtube-automation-agent/blob/master/utils/operator-service.js): `utils/operator-service.js`

### Planning and writing

- [Topic strategy](https://github.com/darkzogx/youtube-automation-agent/blob/master/agents/content-strategy-agent.js): `agents/content-strategy-agent.js`
- [Channel operator](https://github.com/darkzogx/youtube-automation-agent/blob/master/utils/autonomous-channel-operator.js): `utils/autonomous-channel-operator.js`
- [Script writer](https://github.com/darkzogx/youtube-automation-agent/blob/master/agents/script-writer-agent.js): `agents/script-writer-agent.js`
- [Text generation](https://github.com/darkzogx/youtube-automation-agent/blob/master/utils/ai-text-service.js): `utils/ai-text-service.js`
- [SEO metadata](https://github.com/darkzogx/youtube-automation-agent/blob/master/agents/seo-optimizer-agent.js): `agents/seo-optimizer-agent.js`

### Video production

- [Production manager](https://github.com/darkzogx/youtube-automation-agent/blob/master/agents/production-management-agent.js): `agents/production-management-agent.js`
- [Video generation](https://github.com/darkzogx/youtube-automation-agent/blob/master/utils/ai-video-generator.js): `utils/ai-video-generator.js`
- [Media provider routing](https://github.com/darkzogx/youtube-automation-agent/blob/master/utils/media-generation-service.js): `utils/media-generation-service.js`
- [Video providers](https://github.com/darkzogx/youtube-automation-agent/blob/master/utils/video-providers.js): `utils/video-providers.js`
- [Scene repair](https://github.com/darkzogx/youtube-automation-agent/blob/master/utils/scene-repair-service.js): `utils/scene-repair-service.js`
- [Shorts repurposing](https://github.com/darkzogx/youtube-automation-agent/blob/master/utils/shorts-repurposing-service.js): `utils/shorts-repurposing-service.js`

### Review and publishing

- [Human approval](https://github.com/darkzogx/youtube-automation-agent/blob/master/index.js): `index.js`
- [Publishing scheduler](https://github.com/darkzogx/youtube-automation-agent/blob/master/agents/publishing-scheduling-agent.js): `agents/publishing-scheduling-agent.js`
- [Discoverability checks](https://github.com/darkzogx/youtube-automation-agent/blob/master/utils/discoverability-service.js): `utils/discoverability-service.js`

### Learning and growth

- [Audience engagement](https://github.com/darkzogx/youtube-automation-agent/blob/master/utils/audience-engagement-service.js): `utils/audience-engagement-service.js`
- [Analytics optimizer](https://github.com/darkzogx/youtube-automation-agent/blob/master/agents/analytics-optimization-agent.js): `agents/analytics-optimization-agent.js`
- [Channel learning](https://github.com/darkzogx/youtube-automation-agent/blob/master/utils/channel-learning-engine.js): `utils/channel-learning-engine.js`
- [Scene retention](https://github.com/darkzogx/youtube-automation-agent/blob/master/utils/scene-retention-engine.js): `utils/scene-retention-engine.js`
- [Growth experiments](https://github.com/darkzogx/youtube-automation-agent/blob/master/utils/growth-experiment-service.js): `utils/growth-experiment-service.js`

### Other components

- **Channel owner**
- **YouTube**

## Connections

- Channel owner → Dashboard: operates (evidence: `README.md`)
- Dashboard → Application server: requests (evidence: `index.js`)
- Application server → Channel database: reads and writes (evidence: `index.js`)
- Application server → Topic strategy: initializes (evidence: `index.js`)
- Application server → Script writer: initializes (evidence: `index.js`)
- Application server → Production manager: runs jobs (evidence: `index.js`)
- Application server → Publishing scheduler: routes publishing (evidence: `index.js`)
- Application server → Channel operator: routes operator (evidence: `index.js`)
- Application server → Operator controls: uses controls (evidence: `index.js`)
- Channel operator → Topic strategy: plans topics (evidence: `README.md`)
- Topic strategy → Text generation: generates strategy (evidence: `agents/content-strategy-agent.js`)
- Script writer → Text generation: generates scripts (evidence: `agents/script-writer-agent.js`)
- Topic strategy → Script writer: feeds production (evidence: `README.md`)
- Script writer → SEO metadata: creates metadata (evidence: `README.md`)
- Production manager → Video generation: generates media (evidence: `agents/production-management-agent.js`)
- Video generation → Media provider routing: requests clips (evidence: `utils/ai-video-generator.js`)
- Media provider routing → Video providers: routes generation (evidence: `utils/media-generation-service.js`)
- Production manager → Scene repair: enables repair (evidence: `agents/production-management-agent.js`)
- Channel owner → Human approval: reviews content (evidence: `README.md`)
- Human approval → Publishing scheduler: approves scheduling (evidence: `README.md`)
- Publishing scheduler → YouTube: uploads approved (evidence: `README.md`)
- Human approval → Discoverability checks: runs preflight (evidence: `README.md`)
- Human approval → Shorts repurposing: repurposes approved (evidence: `README.md`)
- YouTube → Analytics optimizer: provides outcomes (evidence: `README.md`)
- Analytics optimizer → Channel learning: proposes lessons (evidence: `agents/analytics-optimization-agent.js`)
- Channel learning → Scene retention: analyzes scenes (evidence: `utils/channel-learning-engine.js`)
- Channel learning → Growth experiments: informs tests (evidence: `README.md`)
- Channel owner → Channel learning: approves lessons (evidence: `README.md`)
- YouTube → Audience engagement: supplies comments (evidence: `README.md`)
- Audience engagement → Channel owner: presents reply drafts (evidence: `README.md`)