# hkuds/vimax architecture

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

- Interactive diagram: https://gitdiagram.com/hkuds/vimax
- Repository: https://github.com/hkuds/vimax
- Video tour (about a minute): https://gitdiagram.com/hkuds/vimax/video

## Overview

ViMax turns an idea, screenplay, or novel into generated video, coordinating narrative planning, storyboarding, visual assets, shot rendering, and interactive project workspaces. The documented principal workflow runs from an idea through script and storyboard into video; Script2Video and Novel2Video provide distinct entry paths. Source excerpts show portions of the Idea2Video and Script2Video orchestration, image-provider calls, and Web UI bridge. Several documented capabilities are represented by their existing pipeline or directory paths because their implementation was not sampled.

Main entry points: [`pipelines/script2video_pipeline.py`](https://github.com/hkuds/vimax/blob/main/pipelines/script2video_pipeline.py) (Script2Video), [`pipelines/novel2movie_pipeline.py`](https://github.com/hkuds/vimax/blob/main/pipelines/novel2movie_pipeline.py) (Novel2Video), [`pipelines/idea2video_pipeline.py`](https://github.com/hkuds/vimax/blob/main/pipelines/idea2video_pipeline.py) (Idea2Video), [`web/server.mjs`](https://github.com/hkuds/vimax/blob/main/web/server.mjs) (Web API server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_creation["Creation workflows"]
  node_idea["Idea2Video"]
  node_script["Script2Video"]
  node_novel["Novel2Video"]
end

subgraph group_agents["Creative agents"]
  node_novelcompress["Novel compression"]
  node_eventextract["Event extraction<br/>[event_extractor.py]"]
  node_sceneextract["Scene extraction<br/>[scene_extractor.py]"]
  node_globalplan["Global planning"]
  node_screenwriter["Screenwriting<br/>[screenwriter.py]"]
  node_characters["Character extraction"]
  node_portraits["Character portraits"]
  node_storyboard["Storyboard design"]
  node_references["Reference selection"]
  node_camera["Camera images"]
end

subgraph group_media["Media generation"]
  node_render["Shot rendering<br/>[render_backend.py]"]
  node_imageproviders["Image providers"]
  node_videoproviders["Video providers"]
end

subgraph group_workspace["Interactive workspaces"]
  node_tui["Agent TUI<br/>[cli.tsx]"]
  node_agentloop["Agent loop<br/>[loop.py]"]
  node_webui["Web workspace<br/>[App.tsx]"]
  node_webapi["Web API server<br/>[server.mjs]"]
  node_sessionindex[("Session index<br/>[session_index.py]")]
  node_artifacts["Project artifacts<br/>[server-lib.mjs]"]
end

node_creator(("Creator"))

node_creator -->|"submits concept"| node_idea
node_idea -->|"develops story"| node_screenwriter
node_idea -->|"extracts characters"| node_characters
node_idea -->|"generates portraits"| node_portraits
node_idea -->|"hands off script"| node_script
node_script -->|"designs storyboard"| node_storyboard
node_script -->|"constructs camera tree"| node_camera
node_script -->|"renders shots"| node_render
node_script -->|"selects references"| node_references
node_render -.->|"requests images"| node_imageproviders
node_render -.->|"requests video"| node_videoproviders
node_creator -->|"provides screenplay"| node_script
node_creator -->|"provides novel"| node_novel
node_novel -->|"compresses narrative"| node_novelcompress
node_novel -->|"extracts events"| node_eventextract
node_novel -->|"plans scenes"| node_sceneextract
node_novel -->|"tracks characters"| node_globalplan
node_novel -.->|"uses video pipeline"| node_script
node_creator -->|"starts conversation"| node_tui
node_tui -.->|"sends requests"| node_agentloop
node_creator -->|"manages project"| node_webui
node_webui -->|"calls API"| node_webapi
node_webapi -.->|"starts agent"| node_agentloop
node_webapi -.->|"reads sessions"| node_sessionindex
node_webapi -->|"streams artifacts"| node_artifacts

click node_idea "https://github.com/hkuds/vimax/blob/main/pipelines/idea2video_pipeline.py"
click node_script "https://github.com/hkuds/vimax/blob/main/pipelines/script2video_pipeline.py"
click node_novel "https://github.com/hkuds/vimax/blob/main/pipelines/novel2movie_pipeline.py"
click node_novelcompress "https://github.com/hkuds/vimax/blob/main/agents/novel_compressor.py"
click node_eventextract "https://github.com/hkuds/vimax/blob/main/agents/event_extractor.py"
click node_sceneextract "https://github.com/hkuds/vimax/blob/main/agents/scene_extractor.py"
click node_globalplan "https://github.com/hkuds/vimax/blob/main/agents/global_information_planner.py"
click node_screenwriter "https://github.com/hkuds/vimax/blob/main/agents/screenwriter.py"
click node_characters "https://github.com/hkuds/vimax/blob/main/agents/character_extractor.py"
click node_portraits "https://github.com/hkuds/vimax/blob/main/agents/character_portraits_generator.py"
click node_storyboard "https://github.com/hkuds/vimax/blob/main/agents/storyboard_artist.py"
click node_references "https://github.com/hkuds/vimax/blob/main/agents/reference_image_selector.py"
click node_camera "https://github.com/hkuds/vimax/blob/main/agents/camera_image_generator.py"
click node_render "https://github.com/hkuds/vimax/blob/main/tools/render_backend.py"
click node_imageproviders "https://github.com/hkuds/vimax/tree/main/tools"
click node_videoproviders "https://github.com/hkuds/vimax/tree/main/tools"
click node_tui "https://github.com/hkuds/vimax/blob/main/ui/src/cli.tsx"
click node_agentloop "https://github.com/hkuds/vimax/blob/main/agent_runtime/loop.py"
click node_webui "https://github.com/hkuds/vimax/blob/main/web/src/App.tsx"
click node_webapi "https://github.com/hkuds/vimax/blob/main/web/server.mjs"
click node_sessionindex "https://github.com/hkuds/vimax/blob/main/agent_runtime/session_index.py"
click node_artifacts "https://github.com/hkuds/vimax/blob/main/web/server-lib.mjs"

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_idea,node_script,node_novel toneBlue
class node_novelcompress,node_eventextract,node_sceneextract,node_globalplan,node_screenwriter,node_characters,node_portraits,node_storyboard,node_references,node_camera toneAmber
class node_render,node_imageproviders,node_videoproviders toneMint
class node_tui,node_agentloop,node_webui,node_webapi,node_sessionindex,node_artifacts toneRose
class node_creator toneIndigo
```

## Components

### Creation workflows

- [Idea2Video](https://github.com/hkuds/vimax/blob/main/pipelines/idea2video_pipeline.py): `pipelines/idea2video_pipeline.py`
- [Script2Video](https://github.com/hkuds/vimax/blob/main/pipelines/script2video_pipeline.py): `pipelines/script2video_pipeline.py`
- [Novel2Video](https://github.com/hkuds/vimax/blob/main/pipelines/novel2movie_pipeline.py): `pipelines/novel2movie_pipeline.py`

### Creative agents

- [Novel compression](https://github.com/hkuds/vimax/blob/main/agents/novel_compressor.py): `agents/novel_compressor.py`
- [Event extraction](https://github.com/hkuds/vimax/blob/main/agents/event_extractor.py): `agents/event_extractor.py`
- [Scene extraction](https://github.com/hkuds/vimax/blob/main/agents/scene_extractor.py): `agents/scene_extractor.py`
- [Global planning](https://github.com/hkuds/vimax/blob/main/agents/global_information_planner.py): `agents/global_information_planner.py`
- [Screenwriting](https://github.com/hkuds/vimax/blob/main/agents/screenwriter.py): `agents/screenwriter.py`
- [Character extraction](https://github.com/hkuds/vimax/blob/main/agents/character_extractor.py): `agents/character_extractor.py`
- [Character portraits](https://github.com/hkuds/vimax/blob/main/agents/character_portraits_generator.py): `agents/character_portraits_generator.py`
- [Storyboard design](https://github.com/hkuds/vimax/blob/main/agents/storyboard_artist.py): `agents/storyboard_artist.py`
- [Reference selection](https://github.com/hkuds/vimax/blob/main/agents/reference_image_selector.py): `agents/reference_image_selector.py`
- [Camera images](https://github.com/hkuds/vimax/blob/main/agents/camera_image_generator.py): `agents/camera_image_generator.py`

### Media generation

- [Shot rendering](https://github.com/hkuds/vimax/blob/main/tools/render_backend.py): `tools/render_backend.py`
- [Image providers](https://github.com/hkuds/vimax/tree/main/tools): `tools`
- [Video providers](https://github.com/hkuds/vimax/tree/main/tools): `tools`

### Interactive workspaces

- [Agent TUI](https://github.com/hkuds/vimax/blob/main/ui/src/cli.tsx): `ui/src/cli.tsx`
- [Agent loop](https://github.com/hkuds/vimax/blob/main/agent_runtime/loop.py): `agent_runtime/loop.py`
- [Web workspace](https://github.com/hkuds/vimax/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Web API server](https://github.com/hkuds/vimax/blob/main/web/server.mjs): `web/server.mjs`
- [Session index](https://github.com/hkuds/vimax/blob/main/agent_runtime/session_index.py): `agent_runtime/session_index.py`
- [Project artifacts](https://github.com/hkuds/vimax/blob/main/web/server-lib.mjs): `web/server-lib.mjs`

### Other components

- **Creator**

## Connections

- Creator → Idea2Video: submits concept
- Idea2Video → Screenwriting: develops story (evidence: `pipelines/idea2video_pipeline.py`)
- Idea2Video → Character extraction: extracts characters (evidence: `pipelines/idea2video_pipeline.py`)
- Idea2Video → Character portraits: generates portraits (evidence: `pipelines/idea2video_pipeline.py`)
- Idea2Video → Script2Video: hands off script (evidence: `pipelines/idea2video_pipeline.py`)
- Script2Video → Storyboard design: designs storyboard (evidence: `pipelines/script2video_pipeline.py`)
- Script2Video → Camera images: constructs camera tree (evidence: `pipelines/script2video_pipeline.py`)
- Script2Video → Shot rendering: renders shots (evidence: `pipelines/script2video_pipeline.py`)
- Script2Video → Reference selection: selects references (evidence: `pipelines/script2video_pipeline.py`)
- Shot rendering → Image providers: requests images
- Shot rendering → Video providers: requests video
- Creator → Script2Video: provides screenplay
- Creator → Novel2Video: provides novel
- Novel2Video → Novel compression: compresses narrative
- Novel2Video → Event extraction: extracts events
- Novel2Video → Scene extraction: plans scenes
- Novel2Video → Global planning: tracks characters (evidence: `pipelines/novel2movie_pipeline.py`)
- Novel2Video → Script2Video: uses video pipeline
- Creator → Agent TUI: starts conversation
- Agent TUI → Agent loop: sends requests
- Creator → Web workspace: manages project
- Web workspace → Web API server: calls API (evidence: `web/src/App.tsx`)
- Web API server → Agent loop: starts agent
- Web API server → Session index: reads sessions
- Web API server → Project artifacts: streams artifacts (evidence: `web/server.mjs`)
