# heroesjouney/aimoviestudiov2 architecture

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

- Interactive diagram: https://gitdiagram.com/heroesjouney/aimoviestudiov2
- Repository: https://github.com/heroesjouney/aimoviestudiov2

## Overview

AI Movie Studio 2 is a browser-based AI filmmaking workstation. Its documented workflow moves from screenplay or project setup through scene and shot design, camera previs, image/video generation, audio, timeline assembly, and export. The graph preserves those stages and the driver abstraction that supports local ComfyUI and cloud providers. Source excerpts show router registration, asset storage, generation-driver selection, and screenplay parsing; other documented capabilities are included, but their internal links are omitted where implementation evidence was not sampled.

Main entry points: [`backend/app.py`](https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/app.py) (FastAPI Application), [`backend/core/drivers/__init__.py`](https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/core/drivers/__init__.py) (Driver Registry), [`backend/api/routes_shots.py`](https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/api/routes_shots.py) (Shot Management), [`frontend/src/app/project/[id]/page.tsx`](https://github.com/heroesjouney/aimoviestudiov2/blob/main/frontend/src/app/project/%5Bid%5D/page.tsx) (Project Workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace & Story"]
  node_webapp["Studio Web App<br/>[page.tsx]"]
  node_project_ui["Project Workspace<br/>[page.tsx]"]
  node_projects_api["Project API<br/>[routes_projects.py]"]
  node_screenplay_ui["Screenplay Import"]
  node_screenplay_api["Screenplay API"]
  node_screenplay_parser["Screenplay Parser"]
  node_scenes["Scene Management<br/>[routes_scenes.py]"]
  node_asset_library["Asset Vault UI<br/>[MediaLibrary.tsx]"]
  node_assets_api["Asset Management<br/>[routes_assets.py]"]
end

subgraph group_visual["Visual Planning"]
  node_camera_ui["3D Camera Director<br/>[CameraDirector.tsx]"]
  node_previs_ui["3D Previs<br/>[PrevisStage.tsx]"]
  node_previs_api["Previs API<br/>[routes_previs.py]"]
  node_shots_ui["Shot Composer"]
  node_shots_api["Shot Management<br/>[routes_shots.py]"]
  node_prompt_builder["Prompt Builder<br/>[prompt_builder.py]"]
end

subgraph group_generation["AI Generation"]
  node_generation_api["Image &amp; Video Jobs<br/>[routes_generate.py]"]
  node_driver_registry["Driver Registry<br/>[__init__.py]"]
  node_driver_contract["Driver Contracts<br/>[base.py]"]
  node_comfy_image["ComfyUI Image<br/>[comfy_image.py]"]
  node_comfy_video["ComfyUI Video<br/>[comfy_video.py]"]
  node_audio_drivers["Audio Drivers<br/>[comfy_audio.py]"]
end

subgraph group_post["Audio &amp; Post"]
  node_audio_api["Audio Jobs<br/>[routes_audio.py]"]
  node_timeline_ui["Timeline Editor<br/>[TimelineEditor.tsx]"]
  node_timeline_api["Timeline API<br/>[routes_timeline.py]"]
  node_export_api["Timeline Export<br/>[routes_export.py]"]
end

subgraph group_platform["Application Platform"]
  node_vault["Local Vault<br/>[routes_assets.py]"]
  node_api_client["Frontend API Client<br/>[api.ts]"]
  node_app_server["FastAPI Application<br/>[app.py]"]
end

node_filmmaker(("Filmmaker"))
node_external_models{{"AI Model Providers"}}

node_filmmaker -->|"uses"| node_webapp
node_filmmaker -->|"creates project"| node_project_ui
node_project_ui -.->|"manages projects"| node_projects_api
node_project_ui -.->|"imports screenplay"| node_screenplay_ui
node_screenplay_api -->|"parses screenplay"| node_screenplay_parser
node_screenplay_parser -->|"produces scene data"| node_scenes
node_filmmaker -->|"manages references"| node_asset_library
node_asset_library -.->|"browses assets"| node_assets_api
node_assets_api -->|"reads and writes"| node_vault
node_filmmaker -->|"frames shots"| node_camera_ui
node_filmmaker -->|"blocks camera moves"| node_previs_ui
node_previs_ui -.->|"renders previs"| node_previs_api
node_filmmaker -->|"composes shots"| node_shots_ui
node_shots_ui -.->|"submits shot work"| node_shots_api
node_shots_api -->|"builds prompts"| node_prompt_builder
node_shots_api -->|"selects drivers"| node_driver_registry
node_generation_api -->|"selects image driver"| node_driver_registry
node_driver_registry -->|"instantiates"| node_comfy_image
node_driver_registry -->|"instantiates"| node_comfy_video
node_driver_registry -->|"registers audio drivers"| node_audio_drivers
node_comfy_image -->|"implements"| node_driver_contract
node_comfy_video -->|"implements"| node_driver_contract
node_audio_api -->|"selects audio driver"| node_driver_registry
node_filmmaker -->|"assembles edit"| node_timeline_ui
node_timeline_ui -.->|"manages timeline"| node_timeline_api
node_timeline_api -.->|"exports timeline"| node_export_api
node_comfy_image -.->|"generates images"| node_external_models
node_comfy_video -.->|"generates video"| node_external_models
node_audio_drivers -.->|"generates audio"| node_external_models
node_webapp -.->|"uses API client"| node_api_client
node_api_client -.->|"calls API"| node_app_server
node_app_server -->|"registers routes"| node_assets_api
node_app_server -->|"registers routes"| node_shots_api
node_app_server -->|"registers routes"| node_generation_api
node_app_server -->|"registers routes"| node_audio_api
node_app_server -->|"registers routes"| node_timeline_api
node_app_server -->|"registers routes"| node_export_api
node_app_server -->|"registers routes"| node_screenplay_api
node_app_server -->|"registers routes"| node_previs_api

click node_webapp "https://github.com/heroesjouney/aimoviestudiov2/blob/main/frontend/src/app/page.tsx"
click node_project_ui "https://github.com/heroesjouney/aimoviestudiov2/blob/main/frontend/src/app/project/%5Bid%5D/page.tsx"
click node_projects_api "https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/api/routes_projects.py"
click node_screenplay_ui "https://github.com/heroesjouney/aimoviestudiov2/blob/main/frontend/src/components/studio/ScreenplayImportModal.tsx"
click node_screenplay_api "https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/api/routes_screenplay.py"
click node_screenplay_parser "https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/core/logic/screenplay_parser.py"
click node_scenes "https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/api/routes_scenes.py"
click node_asset_library "https://github.com/heroesjouney/aimoviestudiov2/blob/main/frontend/src/components/library/MediaLibrary.tsx"
click node_assets_api "https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/api/routes_assets.py"
click node_vault "https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/api/routes_assets.py"
click node_camera_ui "https://github.com/heroesjouney/aimoviestudiov2/blob/main/frontend/src/components/camera/CameraDirector.tsx"
click node_previs_ui "https://github.com/heroesjouney/aimoviestudiov2/blob/main/frontend/src/components/previs/PrevisStage.tsx"
click node_previs_api "https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/api/routes_previs.py"
click node_shots_ui "https://github.com/heroesjouney/aimoviestudiov2/blob/main/frontend/src/components/shots/ShotCreatePanel.tsx"
click node_shots_api "https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/api/routes_shots.py"
click node_prompt_builder "https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/core/logic/prompt_builder.py"
click node_generation_api "https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/api/routes_generate.py"
click node_driver_registry "https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/core/drivers/__init__.py"
click node_driver_contract "https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/core/drivers/base.py"
click node_comfy_image "https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/core/drivers/comfy_image.py"
click node_comfy_video "https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/core/drivers/comfy_video.py"
click node_audio_api "https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/api/routes_audio.py"
click node_audio_drivers "https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/core/drivers/comfy_audio.py"
click node_timeline_ui "https://github.com/heroesjouney/aimoviestudiov2/blob/main/frontend/src/components/timeline/TimelineEditor.tsx"
click node_timeline_api "https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/api/routes_timeline.py"
click node_export_api "https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/api/routes_export.py"
click node_api_client "https://github.com/heroesjouney/aimoviestudiov2/blob/main/frontend/src/lib/api.ts"
click node_app_server "https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/app.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_webapp,node_project_ui,node_projects_api,node_screenplay_ui,node_screenplay_api,node_screenplay_parser,node_scenes,node_asset_library,node_assets_api toneBlue
class node_camera_ui,node_previs_ui,node_previs_api,node_shots_ui,node_shots_api,node_prompt_builder toneAmber
class node_generation_api,node_driver_registry,node_driver_contract,node_comfy_image,node_comfy_video,node_audio_drivers toneMint
class node_audio_api,node_timeline_ui,node_timeline_api,node_export_api toneRose
class node_vault,node_api_client,node_app_server,node_filmmaker,node_external_models toneIndigo
```

## Components

### Workspace & Story

- [Studio Web App](https://github.com/heroesjouney/aimoviestudiov2/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Project Workspace](https://github.com/heroesjouney/aimoviestudiov2/blob/main/frontend/src/app/project/%5Bid%5D/page.tsx): `frontend/src/app/project/[id]/page.tsx`
- [Project API](https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/api/routes_projects.py): `backend/api/routes_projects.py`
- [Screenplay Import](https://github.com/heroesjouney/aimoviestudiov2/blob/main/frontend/src/components/studio/ScreenplayImportModal.tsx): `frontend/src/components/studio/ScreenplayImportModal.tsx`
- [Screenplay API](https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/api/routes_screenplay.py): `backend/api/routes_screenplay.py`
- [Screenplay Parser](https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/core/logic/screenplay_parser.py): `backend/core/logic/screenplay_parser.py`
- [Scene Management](https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/api/routes_scenes.py): `backend/api/routes_scenes.py`
- [Asset Vault UI](https://github.com/heroesjouney/aimoviestudiov2/blob/main/frontend/src/components/library/MediaLibrary.tsx): `frontend/src/components/library/MediaLibrary.tsx`
- [Asset Management](https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/api/routes_assets.py): `backend/api/routes_assets.py`

### Visual Planning

- [3D Camera Director](https://github.com/heroesjouney/aimoviestudiov2/blob/main/frontend/src/components/camera/CameraDirector.tsx): `frontend/src/components/camera/CameraDirector.tsx`
- [3D Previs](https://github.com/heroesjouney/aimoviestudiov2/blob/main/frontend/src/components/previs/PrevisStage.tsx): `frontend/src/components/previs/PrevisStage.tsx`
- [Previs API](https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/api/routes_previs.py): `backend/api/routes_previs.py`
- [Shot Composer](https://github.com/heroesjouney/aimoviestudiov2/blob/main/frontend/src/components/shots/ShotCreatePanel.tsx): `frontend/src/components/shots/ShotCreatePanel.tsx`
- [Shot Management](https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/api/routes_shots.py): `backend/api/routes_shots.py`
- [Prompt Builder](https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/core/logic/prompt_builder.py): `backend/core/logic/prompt_builder.py`

### AI Generation

- [Image & Video Jobs](https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/api/routes_generate.py): `backend/api/routes_generate.py`
- [Driver Registry](https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/core/drivers/__init__.py): `backend/core/drivers/__init__.py`
- [Driver Contracts](https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/core/drivers/base.py): `backend/core/drivers/base.py`
- [ComfyUI Image](https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/core/drivers/comfy_image.py): `backend/core/drivers/comfy_image.py`
- [ComfyUI Video](https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/core/drivers/comfy_video.py): `backend/core/drivers/comfy_video.py`
- [Audio Drivers](https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/core/drivers/comfy_audio.py): `backend/core/drivers/comfy_audio.py`

### Audio & Post

- [Audio Jobs](https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/api/routes_audio.py): `backend/api/routes_audio.py`
- [Timeline Editor](https://github.com/heroesjouney/aimoviestudiov2/blob/main/frontend/src/components/timeline/TimelineEditor.tsx): `frontend/src/components/timeline/TimelineEditor.tsx`
- [Timeline API](https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/api/routes_timeline.py): `backend/api/routes_timeline.py`
- [Timeline Export](https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/api/routes_export.py): `backend/api/routes_export.py`

### Application Platform

- [Local Vault](https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/api/routes_assets.py): `backend/api/routes_assets.py`
- [Frontend API Client](https://github.com/heroesjouney/aimoviestudiov2/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [FastAPI Application](https://github.com/heroesjouney/aimoviestudiov2/blob/main/backend/app.py): `backend/app.py`

### Other components

- **Filmmaker**
- **AI Model Providers**

## Connections

- Filmmaker → Studio Web App: uses (evidence: `README.md`)
- Filmmaker → Project Workspace: creates project (evidence: `README.md`)
- Project Workspace → Project API: manages projects
- Project Workspace → Screenplay Import: imports screenplay
- Screenplay API → Screenplay Parser: parses screenplay (evidence: `backend/api/routes_screenplay.py`)
- Screenplay Parser → Scene Management: produces scene data (evidence: `README.md`)
- Filmmaker → Asset Vault UI: manages references (evidence: `README.md`)
- Asset Vault UI → Asset Management: browses assets
- Asset Management → Local Vault: reads and writes (evidence: `backend/api/routes_assets.py`)
- Filmmaker → 3D Camera Director: frames shots (evidence: `README.md`)
- Filmmaker → 3D Previs: blocks camera moves (evidence: `README.md`)
- 3D Previs → Previs API: renders previs
- Filmmaker → Shot Composer: composes shots (evidence: `README.md`)
- Shot Composer → Shot Management: submits shot work
- Shot Management → Prompt Builder: builds prompts (evidence: `backend/api/routes_shots.py`)
- Shot Management → Driver Registry: selects drivers (evidence: `backend/api/routes_shots.py`)
- Image & Video Jobs → Driver Registry: selects image driver (evidence: `backend/api/routes_generate.py`)
- Driver Registry → ComfyUI Image: instantiates (evidence: `backend/core/drivers/__init__.py`)
- Driver Registry → ComfyUI Video: instantiates (evidence: `backend/core/drivers/__init__.py`)
- Driver Registry → Audio Drivers: registers audio drivers (evidence: `backend/core/drivers/__init__.py`)
- ComfyUI Image → Driver Contracts: implements (evidence: `backend/core/drivers/comfy_image.py`)
- ComfyUI Video → Driver Contracts: implements (evidence: `backend/core/drivers/comfy_video.py`)
- Audio Jobs → Driver Registry: selects audio driver (evidence: `backend/api/routes_audio.py`)
- Filmmaker → Timeline Editor: assembles edit (evidence: `README.md`)
- Timeline Editor → Timeline API: manages timeline
- Timeline API → Timeline Export: exports timeline
- ComfyUI Image → AI Model Providers: generates images
- ComfyUI Video → AI Model Providers: generates video
- Audio Drivers → AI Model Providers: generates audio
- Studio Web App → Frontend API Client: uses API client
- Frontend API Client → FastAPI Application: calls API
- FastAPI Application → Asset Management: registers routes (evidence: `backend/app.py`)
- FastAPI Application → Shot Management: registers routes (evidence: `backend/app.py`)
- FastAPI Application → Image & Video Jobs: registers routes (evidence: `backend/app.py`)
- FastAPI Application → Audio Jobs: registers routes (evidence: `backend/app.py`)
- FastAPI Application → Timeline API: registers routes (evidence: `backend/app.py`)
- FastAPI Application → Timeline Export: registers routes (evidence: `backend/app.py`)
- FastAPI Application → Screenplay API: registers routes (evidence: `backend/app.py`)
- FastAPI Application → Previs API: registers routes (evidence: `backend/app.py`)