# wanglevy9/vidforge architecture

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

- Interactive diagram: https://gitdiagram.com/wanglevy9/vidforge
- Repository: https://github.com/wanglevy9/vidforge

## Overview

VidForge is a self-hostable, knowledge-grounded video production workspace. A user enters through the React studio, manages product spaces and materials, then submits a request that the backend runs through material analysis, script planning, video composition, and quality review; quality feedback can trigger bounded replanning. The README also documents human review, checkpoints, media services, analytics/tracing, templates, exports, and task control. Several links reflect the documented architecture rather than inspected implementation; unsampled subsystem details are not inferred.

Main entry points: [`apps/backend/src/app.module.ts`](https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/app.module.ts) (NestJS API), [`apps/backend/src/modules/agent/orchestrator.service.ts`](https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/agent/orchestrator.service.ts) (LangGraph runtime), [`apps/backend/src/modules/agent/agents/script-agent.service.ts`](https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/agent/agents/script-agent.service.ts) (Script agent), [`apps/frontend/src/App.tsx`](https://github.com/wanglevy9/vidforge/blob/main/apps/frontend/src/App.tsx) (React studio)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_studio["Workspace"]
  node_frontend["React studio<br/>[App.tsx]"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_api["NestJS API<br/>[app.module.ts]"]
end

subgraph group_knowledge["Knowledge"]
  node_spaces["Product spaces"]
  node_materials[("Material library")]
  node_scripts["Script planning<br/>[script.service.ts]"]
  node_rag[("Script RAG")]
end

subgraph group_workflow["Agent workflow"]
  node_creation["Creation tasks"]
  node_agent_control[("Run control<br/>[agent.service.ts]")]
  node_orchestrator["LangGraph runtime"]
  node_material_agent["Material agent"]
  node_script_agent["Script agent"]
  node_composition_agent["Composition agent"]
  node_quality_agent["Quality agent"]
  node_memory[("Agent memory")]
end

subgraph group_production["Media and operations"]
  node_provider{{"Generation providers"}}
  node_media["Media composition"]
  node_storage[("Media storage<br/>[storage.service.ts]")]
  node_exports["Video exports<br/>[export.service.ts]"]
  node_analytics["Analytics"]
  node_trace[("Workflow traces<br/>[trace.service.ts]")]
  node_queue["Background queue"]
  node_db[("PostgreSQL<br/>[data-source.ts]")]
  node_redis["Redis and BullMQ<br/>[queue.constants.ts]"]
end

node_user(("User"))

node_user -->|"uses"| node_frontend
node_frontend -->|"calls API"| node_api
node_frontend -.->|"authenticates"| node_auth
node_api -->|"routes space requests"| node_spaces
node_api -->|"routes material requests"| node_materials
node_api -->|"routes creation requests"| node_creation
node_api -->|"controls runs"| node_agent_control
node_api -->|"persists application data"| node_db
node_api -->|"enqueues work"| node_queue
node_queue -->|"uses BullMQ"| node_redis
node_creation -.->|"starts workflow"| node_agent_control
node_agent_control -->|"runs graph"| node_orchestrator
node_orchestrator -->|"dispatches"| node_material_agent
node_orchestrator -->|"dispatches"| node_script_agent
node_orchestrator -->|"dispatches"| node_composition_agent
node_orchestrator -->|"dispatches"| node_quality_agent
node_material_agent -->|"retrieves assets"| node_materials
node_script_agent -->|"retrieves evidence"| node_rag
node_script_agent -->|"uses product knowledge"| node_spaces
node_orchestrator -->|"uses scoped memory"| node_memory
node_quality_agent -->|"feeds replanning"| node_script_agent
node_composition_agent -->|"requests generation"| node_provider
node_composition_agent -->|"composes video"| node_media
node_media -->|"stores artifacts"| node_storage
node_orchestrator -->|"records workflow traces"| node_trace
node_api -.->|"serves analytics"| node_analytics
node_api -.->|"serves exports"| node_exports

click node_frontend "https://github.com/wanglevy9/vidforge/blob/main/apps/frontend/src/App.tsx"
click node_auth "https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/auth/auth.service.ts"
click node_spaces "https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/product-space/product-space.service.ts"
click node_materials "https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/material/material.service.ts"
click node_scripts "https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/script/script.service.ts"
click node_rag "https://github.com/wanglevy9/vidforge/tree/main/apps/backend/src/modules/rag"
click node_api "https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/app.module.ts"
click node_creation "https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/creation/creation.service.ts"
click node_agent_control "https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/agent/agent.service.ts"
click node_orchestrator "https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/agent/orchestrator.service.ts"
click node_material_agent "https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/agent/agents/material-agent.service.ts"
click node_script_agent "https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/agent/agents/script-agent.service.ts"
click node_composition_agent "https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/agent/agents/composition-agent.service.ts"
click node_quality_agent "https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/agent/agents/quality-agent.service.ts"
click node_memory "https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/agent/memory/agent-memory.service.ts"
click node_provider "https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/ai/services/ark-video.service.ts"
click node_media "https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/media/services/composer.service.ts"
click node_storage "https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/media/services/storage.service.ts"
click node_exports "https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/export/export.service.ts"
click node_analytics "https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/analytics/analytics.service.ts"
click node_trace "https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/trace/trace.service.ts"
click node_queue "https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/queue/queue-runner.service.ts"
click node_db "https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/database/data-source.ts"
click node_redis "https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/queue/queue.constants.ts"

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_frontend,node_auth,node_api,node_user toneBlue
class node_spaces,node_materials,node_scripts,node_rag toneAmber
class node_creation,node_agent_control,node_orchestrator,node_material_agent,node_script_agent,node_composition_agent,node_quality_agent,node_memory toneMint
class node_provider,node_media,node_storage,node_exports,node_analytics,node_trace,node_queue,node_db,node_redis toneRose
```

## Components

### Workspace

- [React studio](https://github.com/wanglevy9/vidforge/blob/main/apps/frontend/src/App.tsx): `apps/frontend/src/App.tsx`
- [Authentication](https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/auth/auth.service.ts): `apps/backend/src/modules/auth/auth.service.ts`
- [NestJS API](https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/app.module.ts): `apps/backend/src/app.module.ts`

### Knowledge

- [Product spaces](https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/product-space/product-space.service.ts): `apps/backend/src/modules/product-space/product-space.service.ts`
- [Material library](https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/material/material.service.ts): `apps/backend/src/modules/material/material.service.ts`
- [Script planning](https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/script/script.service.ts): `apps/backend/src/modules/script/script.service.ts`
- [Script RAG](https://github.com/wanglevy9/vidforge/tree/main/apps/backend/src/modules/rag): `apps/backend/src/modules/rag`

### Agent workflow

- [Creation tasks](https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/creation/creation.service.ts): `apps/backend/src/modules/creation/creation.service.ts`
- [Run control](https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/agent/agent.service.ts): `apps/backend/src/modules/agent/agent.service.ts`
- [LangGraph runtime](https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/agent/orchestrator.service.ts): `apps/backend/src/modules/agent/orchestrator.service.ts`
- [Material agent](https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/agent/agents/material-agent.service.ts): `apps/backend/src/modules/agent/agents/material-agent.service.ts`
- [Script agent](https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/agent/agents/script-agent.service.ts): `apps/backend/src/modules/agent/agents/script-agent.service.ts`
- [Composition agent](https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/agent/agents/composition-agent.service.ts): `apps/backend/src/modules/agent/agents/composition-agent.service.ts`
- [Quality agent](https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/agent/agents/quality-agent.service.ts): `apps/backend/src/modules/agent/agents/quality-agent.service.ts`
- [Agent memory](https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/agent/memory/agent-memory.service.ts): `apps/backend/src/modules/agent/memory/agent-memory.service.ts`

### Media and operations

- [Generation providers](https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/ai/services/ark-video.service.ts): `apps/backend/src/modules/ai/services/ark-video.service.ts`
- [Media composition](https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/media/services/composer.service.ts): `apps/backend/src/modules/media/services/composer.service.ts`
- [Media storage](https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/media/services/storage.service.ts): `apps/backend/src/modules/media/services/storage.service.ts`
- [Video exports](https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/export/export.service.ts): `apps/backend/src/modules/export/export.service.ts`
- [Analytics](https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/analytics/analytics.service.ts): `apps/backend/src/modules/analytics/analytics.service.ts`
- [Workflow traces](https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/trace/trace.service.ts): `apps/backend/src/modules/trace/trace.service.ts`
- [Background queue](https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/queue/queue-runner.service.ts): `apps/backend/src/modules/queue/queue-runner.service.ts`
- [PostgreSQL](https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/database/data-source.ts): `apps/backend/src/database/data-source.ts`
- [Redis and BullMQ](https://github.com/wanglevy9/vidforge/blob/main/apps/backend/src/modules/queue/queue.constants.ts): `apps/backend/src/modules/queue/queue.constants.ts`

### Other components

- **User**

## Connections

- User → React studio: uses (evidence: `README.md`)
- React studio → NestJS API: calls API (evidence: `README.md`)
- React studio → Authentication: authenticates
- NestJS API → Product spaces: routes space requests
- NestJS API → Material library: routes material requests
- NestJS API → Creation tasks: routes creation requests
- NestJS API → Run control: controls runs (evidence: `README.md`)
- NestJS API → PostgreSQL: persists application data (evidence: `README.md`)
- NestJS API → Background queue: enqueues work (evidence: `README.md`)
- Background queue → Redis and BullMQ: uses BullMQ (evidence: `README.md`)
- Creation tasks → Run control: starts workflow
- Run control → LangGraph runtime: runs graph (evidence: `README.md`)
- LangGraph runtime → Material agent: dispatches (evidence: `apps/backend/src/modules/agent/orchestrator.service.ts`)
- LangGraph runtime → Script agent: dispatches (evidence: `apps/backend/src/modules/agent/orchestrator.service.ts`)
- LangGraph runtime → Composition agent: dispatches (evidence: `apps/backend/src/modules/agent/orchestrator.service.ts`)
- LangGraph runtime → Quality agent: dispatches (evidence: `apps/backend/src/modules/agent/orchestrator.service.ts`)
- Material agent → Material library: retrieves assets (evidence: `README.md`)
- Script agent → Script RAG: retrieves evidence (evidence: `README.md`)
- Script agent → Product spaces: uses product knowledge (evidence: `README.md`)
- LangGraph runtime → Agent memory: uses scoped memory (evidence: `README.md`)
- Quality agent → Script agent: feeds replanning (evidence: `README.md`)
- Composition agent → Generation providers: requests generation (evidence: `README.md`)
- Composition agent → Media composition: composes video (evidence: `README.md`)
- Media composition → Media storage: stores artifacts (evidence: `README.md`)
- LangGraph runtime → Workflow traces: records workflow traces (evidence: `README.md`)
- NestJS API → Analytics: serves analytics
- NestJS API → Video exports: serves exports
