# fylypovych/vertep architecture

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

- Interactive diagram: https://gitdiagram.com/fylypovych/vertep
- Repository: https://github.com/fylypovych/vertep

## Overview

Vertep is a modular content-production orchestrator: users configure characters and brands, submit jobs through the Web UI or Telegram, and receive rendered videos that can be approved and published. CORE owns job state and dispatches GPU tasks to WORKER nodes; workers return artifacts for CORE-side video assembly. The graph also preserves node administration, setup, and operations capabilities documented in the README. Relationships are limited to excerpted calls or README statements; unsampled subsystems are represented only where documented, with no inferred internal call chains.

Main entry points: [`core/api/job_helpers.py`](https://github.com/fylypovych/vertep/blob/main/core/api/job_helpers.py) (Job lifecycle), [`core/dispatcher.py`](https://github.com/fylypovych/vertep/blob/main/core/dispatcher.py) (GPU dispatch), [`core/pipeline.py`](https://github.com/fylypovych/vertep/blob/main/core/pipeline.py) (Video assembly), [`worker/service.py`](https://github.com/fylypovych/vertep/blob/main/worker/service.py) (GPU worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_creation["Job production"]
  node_jobs["Job lifecycle<br/>[job_helpers.py]"]
  node_jobstore[("Job persistence<br/>[pipeline.py]")]
  node_queue["Task queue<br/>[queue.py]"]
  node_artifacts[("Artifact registry<br/>[artifacts.py]")]
  node_storyboard["Storyboard generation<br/>[storyboard.py]"]
  node_providers["Provider registry<br/>[__init__.py]"]
  node_video["Video assembly<br/>[pipeline.py]"]
  node_engines["Video engines<br/>[video_engines.py]"]
  node_ffmpeg["FFmpeg adapter<br/>[ffmpeg.py]"]
  node_publisher["Publishing"]
  node_channels["Social channels<br/>[base.py]"]
end

subgraph group_cluster["Cluster runtime"]
  node_dispatcher["GPU dispatch<br/>[dispatcher.py]"]
  node_registry[("Worker registry<br/>[node_registry.py]")]
  node_worker["GPU worker<br/>[service.py]"]
  node_roleexec["Task execution<br/>[role_executor.py]"]
  node_comfy["ComfyUI adapter<br/>[comfyui.py]"]
end

subgraph group_management["Administration"]
  node_api["CORE API<br/>[app.py]"]
  node_first_run["First-run setup<br/>[first_run.py]"]
  node_updates["Signed updates<br/>[update_manager.py]"]
  node_backup["Backup service<br/>[backup_service.py]"]
  node_operations["Operations API"]
end

subgraph group_interfaces["User interfaces"]
  node_webui["Web UI<br/>[app.routes.ts]"]
  node_telegram["Telegram bot<br/>[telegram.py]"]
end

node_user(("User"))
node_external_gpu(("Worker nodes"))
node_social(("Social platforms"))

node_user -->|"uses"| node_webui
node_user -->|"messages"| node_telegram
node_webui -.->|"requests"| node_api
node_telegram -->|"creates jobs"| node_jobs
node_api -->|"handles jobs"| node_jobs
node_jobs -->|"records state"| node_jobstore
node_jobs -->|"enqueues tasks"| node_queue
node_dispatcher -.->|"claims tasks"| node_queue
node_dispatcher -.->|"selects workers"| node_registry
node_dispatcher -->|"dispatches work"| node_external_gpu
node_external_gpu -.->|"runs service"| node_worker
node_worker -->|"executes tasks"| node_roleexec
node_roleexec -->|"uses runtime"| node_comfy
node_worker -->|"returns artifacts"| node_artifacts
node_jobs -->|"creates storyboard"| node_storyboard
node_jobs -->|"selects providers"| node_providers
node_jobs -->|"queues assembly"| node_video
node_video -->|"selects engine"| node_engines
node_engines -->|"assembles video"| node_ffmpeg
node_video -->|"registers output"| node_artifacts
node_jobs -.->|"initiates publishing"| node_publisher
node_publisher -.->|"dispatches posts"| node_channels
node_channels -.->|"publishes"| node_social
node_user -->|"configures appliance"| node_first_run
node_user -->|"requests update"| node_updates
node_operations -->|"queues maintenance"| node_updates
node_user -->|"manages backups"| node_backup
node_webui -.->|"administers nodes"| node_registry

click node_webui "https://github.com/fylypovych/vertep/blob/main/web-v2/src/app/app.routes.ts"
click node_telegram "https://github.com/fylypovych/vertep/blob/main/adapters/telegram.py"
click node_api "https://github.com/fylypovych/vertep/blob/main/core/app.py"
click node_jobs "https://github.com/fylypovych/vertep/blob/main/core/api/job_helpers.py"
click node_jobstore "https://github.com/fylypovych/vertep/blob/main/core/pipeline.py"
click node_queue "https://github.com/fylypovych/vertep/blob/main/core/queue.py"
click node_dispatcher "https://github.com/fylypovych/vertep/blob/main/core/dispatcher.py"
click node_registry "https://github.com/fylypovych/vertep/blob/main/core/node_registry.py"
click node_worker "https://github.com/fylypovych/vertep/blob/main/worker/service.py"
click node_roleexec "https://github.com/fylypovych/vertep/blob/main/worker/role_executor.py"
click node_comfy "https://github.com/fylypovych/vertep/blob/main/adapters/comfyui.py"
click node_artifacts "https://github.com/fylypovych/vertep/blob/main/core/artifacts.py"
click node_storyboard "https://github.com/fylypovych/vertep/blob/main/core/storyboard.py"
click node_providers "https://github.com/fylypovych/vertep/blob/main/adapters/providers/__init__.py"
click node_video "https://github.com/fylypovych/vertep/blob/main/core/pipeline.py"
click node_engines "https://github.com/fylypovych/vertep/blob/main/adapters/providers/video_engines.py"
click node_ffmpeg "https://github.com/fylypovych/vertep/blob/main/adapters/ffmpeg.py"
click node_publisher "https://github.com/fylypovych/vertep/blob/main/services/publisher_service.py"
click node_channels "https://github.com/fylypovych/vertep/blob/main/publishers/base.py"
click node_first_run "https://github.com/fylypovych/vertep/blob/main/core/first_run.py"
click node_updates "https://github.com/fylypovych/vertep/blob/main/core/update_manager.py"
click node_backup "https://github.com/fylypovych/vertep/blob/main/services/backup_service.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_jobs,node_jobstore,node_queue,node_artifacts,node_storyboard,node_providers,node_video,node_engines,node_ffmpeg,node_publisher,node_channels,node_user toneBlue
class node_dispatcher,node_registry,node_worker,node_roleexec,node_comfy toneAmber
class node_api,node_first_run,node_updates,node_backup,node_operations toneMint
class node_webui,node_telegram,node_external_gpu toneRose
class node_social toneIndigo
```

## Components

### Job production

- [Job lifecycle](https://github.com/fylypovych/vertep/blob/main/core/api/job_helpers.py): `core/api/job_helpers.py`
- [Job persistence](https://github.com/fylypovych/vertep/blob/main/core/pipeline.py): `core/pipeline.py`
- [Task queue](https://github.com/fylypovych/vertep/blob/main/core/queue.py): `core/queue.py`
- [Artifact registry](https://github.com/fylypovych/vertep/blob/main/core/artifacts.py): `core/artifacts.py`
- [Storyboard generation](https://github.com/fylypovych/vertep/blob/main/core/storyboard.py): `core/storyboard.py`
- [Provider registry](https://github.com/fylypovych/vertep/blob/main/adapters/providers/__init__.py): `adapters/providers/__init__.py`
- [Video assembly](https://github.com/fylypovych/vertep/blob/main/core/pipeline.py): `core/pipeline.py`
- [Video engines](https://github.com/fylypovych/vertep/blob/main/adapters/providers/video_engines.py): `adapters/providers/video_engines.py`
- [FFmpeg adapter](https://github.com/fylypovych/vertep/blob/main/adapters/ffmpeg.py): `adapters/ffmpeg.py`
- [Publishing](https://github.com/fylypovych/vertep/blob/main/services/publisher_service.py): `services/publisher_service.py`
- [Social channels](https://github.com/fylypovych/vertep/blob/main/publishers/base.py): `publishers/base.py`

### Cluster runtime

- [GPU dispatch](https://github.com/fylypovych/vertep/blob/main/core/dispatcher.py): `core/dispatcher.py`
- [Worker registry](https://github.com/fylypovych/vertep/blob/main/core/node_registry.py): `core/node_registry.py`
- [GPU worker](https://github.com/fylypovych/vertep/blob/main/worker/service.py): `worker/service.py`
- [Task execution](https://github.com/fylypovych/vertep/blob/main/worker/role_executor.py): `worker/role_executor.py`
- [ComfyUI adapter](https://github.com/fylypovych/vertep/blob/main/adapters/comfyui.py): `adapters/comfyui.py`

### Administration

- [CORE API](https://github.com/fylypovych/vertep/blob/main/core/app.py): `core/app.py`
- [First-run setup](https://github.com/fylypovych/vertep/blob/main/core/first_run.py): `core/first_run.py`
- [Signed updates](https://github.com/fylypovych/vertep/blob/main/core/update_manager.py): `core/update_manager.py`
- [Backup service](https://github.com/fylypovych/vertep/blob/main/services/backup_service.py): `services/backup_service.py`
- **Operations API**

### User interfaces

- [Web UI](https://github.com/fylypovych/vertep/blob/main/web-v2/src/app/app.routes.ts): `web-v2/src/app/app.routes.ts`
- [Telegram bot](https://github.com/fylypovych/vertep/blob/main/adapters/telegram.py): `adapters/telegram.py`

### Other components

- **User**
- **Worker nodes**
- **Social platforms**

## Connections

- User → Web UI: uses (evidence: `README.md`)
- User → Telegram bot: messages (evidence: `README.md`)
- Web UI → CORE API: requests
- Telegram bot → Job lifecycle: creates jobs (evidence: `README.md`)
- CORE API → Job lifecycle: handles jobs (evidence: `core/api/job_helpers.py`)
- Job lifecycle → Job persistence: records state (evidence: `core/api/job_helpers.py`)
- Job lifecycle → Task queue: enqueues tasks (evidence: `core/api/job_helpers.py`)
- GPU dispatch → Task queue: claims tasks
- GPU dispatch → Worker registry: selects workers
- GPU dispatch → Worker nodes: dispatches work (evidence: `README.md`)
- Worker nodes → GPU worker: runs service
- GPU worker → Task execution: executes tasks (evidence: `worker/service.py`)
- Task execution → ComfyUI adapter: uses runtime
- GPU worker → Artifact registry: returns artifacts (evidence: `README.md`)
- Job lifecycle → Storyboard generation: creates storyboard (evidence: `core/api/job_helpers.py`)
- Job lifecycle → Provider registry: selects providers (evidence: `core/api/job_helpers.py`)
- Job lifecycle → Video assembly: queues assembly (evidence: `core/api/job_helpers.py`)
- Video assembly → Video engines: selects engine (evidence: `core/pipeline.py`)
- Video engines → FFmpeg adapter: assembles video (evidence: `adapters/providers/video_engines.py`)
- Video assembly → Artifact registry: registers output (evidence: `core/api/job_helpers.py`)
- Job lifecycle → Publishing: initiates publishing
- Publishing → Social channels: dispatches posts
- Social channels → Social platforms: publishes
- User → First-run setup: configures appliance (evidence: `README.md`)
- User → Signed updates: requests update (evidence: `README.md`)
- Operations API → Signed updates: queues maintenance (evidence: `README.md`)
- User → Backup service: manages backups (evidence: `README.md`)
- Web UI → Worker registry: administers nodes
