# nithin0553/cutsceneai-studio architecture

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

- Interactive diagram: https://gitdiagram.com/nithin0553/cutsceneai-studio
- Repository: https://github.com/nithin0553/cutsceneai-studio
- Video tour (about a minute): https://gitdiagram.com/nithin0553/cutsceneai-studio/video

## Overview

CutSceneAI Studio turns a creative brief into a validated cinematic plan, then offers preview, dialogue-audio, and Unreal-export branches. The README documents these capabilities; sampled source confirms the API-to-preview path, CIR validation, preview-to-Unreal compilation, and dialogue bundle generation and verification. Other API wiring and some subsystem internals are represented only where documented, so uncertain call relationships are omitted.

Main entry points: [`backend/app/main.py`](https://github.com/nithin0553/cutsceneai-studio/blob/main/backend/app/main.py) (FastAPI app), [`backend/app/api/preview.py`](https://github.com/nithin0553/cutsceneai-studio/blob/main/backend/app/api/preview.py) (Preview API), [`backend/app/api/dialogue.py`](https://github.com/nithin0553/cutsceneai-studio/blob/main/backend/app/api/dialogue.py) (Dialogue API), [`backend/app/api/unreal.py`](https://github.com/nithin0553/cutsceneai-studio/blob/main/backend/app/api/unreal.py) (Unreal API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_cir_api["CIR validation API<br/>[cir.py]"]
  node_director_api["Director API<br/>[director.py]"]
  node_preview_api["Preview API<br/>[preview.py]"]
  node_dialogue_api["Dialogue API<br/>[dialogue.py]"]
  node_unreal_api["Unreal API<br/>[unreal.py]"]
end

subgraph group_planning["Cinematic Planning"]
  node_cir_models["CIR contract<br/>[models.py]"]
  node_cir_validation["CIR validation<br/>[validation.py]"]
  node_director_service["Director service<br/>[director.py]"]
  node_director_openai["OpenAI director<br/>[openai_director.py]"]
end

subgraph group_preview["Preview Pipeline"]
  node_preview_compiler["Manifest compiler<br/>[compiler.py]"]
  node_storyboard["Storyboard renderer<br/>[rendering.py]"]
end

subgraph group_dialogue["Dialogue Pipeline"]
  node_dialogue_planning["Cue planning<br/>[planning.py]"]
  node_dialogue_service["Audio bundling<br/>[service.py]"]
  node_dialogue_audio["WAV processing<br/>[audio.py]"]
  node_dialogue_loading["Bundle verification<br/>[loading.py]"]
end

subgraph group_unreal["Unreal Export"]
  node_unreal_compiler["Sequencer compiler<br/>[compiler.py]"]
  node_unreal_conversion["Engine conversion<br/>[conversion.py]"]
  node_unreal_dialogue["Dialogue importer<br/>[dialogue_import.py]"]
  node_unreal_rendering["Editor script renderer<br/>[rendering.py]"]
end

node_creator(("Creative user"))
node_openai(("OpenAI"))
node_speech_service(("Speech provider"))
node_unreal_editor(("Unreal Editor"))

node_creator -->|"submits brief"| node_director_api
node_api_app -->|"dispatches"| node_cir_api
node_api_app -->|"dispatches"| node_director_api
node_api_app -->|"dispatches"| node_preview_api
node_api_app -->|"dispatches"| node_dialogue_api
node_api_app -->|"dispatches"| node_unreal_api
node_cir_api -->|"parses project"| node_cir_models
node_cir_api -->|"validates"| node_cir_validation
node_director_api -->|"requests generation"| node_director_service
node_director_service -->|"generates with"| node_director_openai
node_director_openai -->|"requests structured CIR"| node_openai
node_director_service -->|"validates result"| node_cir_validation
node_preview_api -->|"validates input"| node_cir_validation
node_preview_api -->|"compiles project"| node_preview_compiler
node_preview_api -->|"renders manifest"| node_storyboard
node_preview_compiler -->|"checks project"| node_cir_validation
node_dialogue_api -->|"plans cues"| node_dialogue_planning
node_dialogue_api -->|"builds audio bundle"| node_dialogue_service
node_dialogue_service -->|"uses cue plan"| node_dialogue_planning
node_dialogue_service -->|"processes WAV"| node_dialogue_audio
node_dialogue_service -.->|"synthesizes speech"| node_speech_service
node_dialogue_api -->|"verifies uploaded bundle"| node_dialogue_loading
node_unreal_api -->|"compiles export"| node_unreal_compiler
node_unreal_compiler -->|"compiles preview data"| node_preview_compiler
node_unreal_compiler -->|"converts engine values"| node_unreal_conversion
node_unreal_api -->|"imports dialogue bundle"| node_unreal_dialogue
node_unreal_dialogue -->|"verifies bundle"| node_dialogue_loading
node_unreal_api -->|"renders import script"| node_unreal_rendering
node_unreal_editor -->|"runs generated script"| node_unreal_rendering

click node_api_app "https://github.com/nithin0553/cutsceneai-studio/blob/main/backend/app/main.py"
click node_cir_api "https://github.com/nithin0553/cutsceneai-studio/blob/main/backend/app/api/cir.py"
click node_director_api "https://github.com/nithin0553/cutsceneai-studio/blob/main/backend/app/api/director.py"
click node_preview_api "https://github.com/nithin0553/cutsceneai-studio/blob/main/backend/app/api/preview.py"
click node_dialogue_api "https://github.com/nithin0553/cutsceneai-studio/blob/main/backend/app/api/dialogue.py"
click node_unreal_api "https://github.com/nithin0553/cutsceneai-studio/blob/main/backend/app/api/unreal.py"
click node_cir_models "https://github.com/nithin0553/cutsceneai-studio/blob/main/cir/src/cutsceneai_cir/models.py"
click node_cir_validation "https://github.com/nithin0553/cutsceneai-studio/blob/main/cir/src/cutsceneai_cir/validation.py"
click node_director_service "https://github.com/nithin0553/cutsceneai-studio/blob/main/backend/app/services/director.py"
click node_director_openai "https://github.com/nithin0553/cutsceneai-studio/blob/main/backend/app/services/openai_director.py"
click node_preview_compiler "https://github.com/nithin0553/cutsceneai-studio/blob/main/preview/src/cutsceneai_preview/compiler.py"
click node_storyboard "https://github.com/nithin0553/cutsceneai-studio/blob/main/preview/src/cutsceneai_preview/rendering.py"
click node_dialogue_planning "https://github.com/nithin0553/cutsceneai-studio/blob/main/dialogue/src/cutsceneai_dialogue/planning.py"
click node_dialogue_service "https://github.com/nithin0553/cutsceneai-studio/blob/main/dialogue/src/cutsceneai_dialogue/service.py"
click node_dialogue_audio "https://github.com/nithin0553/cutsceneai-studio/blob/main/dialogue/src/cutsceneai_dialogue/audio.py"
click node_dialogue_loading "https://github.com/nithin0553/cutsceneai-studio/blob/main/dialogue/src/cutsceneai_dialogue/loading.py"
click node_unreal_compiler "https://github.com/nithin0553/cutsceneai-studio/blob/main/adapters/unreal/src/cutsceneai_unreal/compiler.py"
click node_unreal_conversion "https://github.com/nithin0553/cutsceneai-studio/blob/main/adapters/unreal/src/cutsceneai_unreal/conversion.py"
click node_unreal_dialogue "https://github.com/nithin0553/cutsceneai-studio/blob/main/adapters/unreal/src/cutsceneai_unreal/dialogue_import.py"
click node_unreal_rendering "https://github.com/nithin0553/cutsceneai-studio/blob/main/adapters/unreal/src/cutsceneai_unreal/rendering.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_api_app,node_cir_api,node_director_api,node_preview_api,node_dialogue_api,node_unreal_api,node_creator toneBlue
class node_cir_models,node_cir_validation,node_director_service,node_director_openai toneAmber
class node_preview_compiler,node_storyboard toneMint
class node_dialogue_planning,node_dialogue_service,node_dialogue_audio,node_dialogue_loading toneRose
class node_unreal_compiler,node_unreal_conversion,node_unreal_dialogue,node_unreal_rendering,node_openai,node_speech_service,node_unreal_editor toneIndigo
```

## Components

### HTTP API

- [FastAPI app](https://github.com/nithin0553/cutsceneai-studio/blob/main/backend/app/main.py): `backend/app/main.py`
- [CIR validation API](https://github.com/nithin0553/cutsceneai-studio/blob/main/backend/app/api/cir.py): `backend/app/api/cir.py`
- [Director API](https://github.com/nithin0553/cutsceneai-studio/blob/main/backend/app/api/director.py): `backend/app/api/director.py`
- [Preview API](https://github.com/nithin0553/cutsceneai-studio/blob/main/backend/app/api/preview.py): `backend/app/api/preview.py`
- [Dialogue API](https://github.com/nithin0553/cutsceneai-studio/blob/main/backend/app/api/dialogue.py): `backend/app/api/dialogue.py`
- [Unreal API](https://github.com/nithin0553/cutsceneai-studio/blob/main/backend/app/api/unreal.py): `backend/app/api/unreal.py`

### Cinematic Planning

- [CIR contract](https://github.com/nithin0553/cutsceneai-studio/blob/main/cir/src/cutsceneai_cir/models.py): `cir/src/cutsceneai_cir/models.py`
- [CIR validation](https://github.com/nithin0553/cutsceneai-studio/blob/main/cir/src/cutsceneai_cir/validation.py): `cir/src/cutsceneai_cir/validation.py`
- [Director service](https://github.com/nithin0553/cutsceneai-studio/blob/main/backend/app/services/director.py): `backend/app/services/director.py`
- [OpenAI director](https://github.com/nithin0553/cutsceneai-studio/blob/main/backend/app/services/openai_director.py): `backend/app/services/openai_director.py`

### Preview Pipeline

- [Manifest compiler](https://github.com/nithin0553/cutsceneai-studio/blob/main/preview/src/cutsceneai_preview/compiler.py): `preview/src/cutsceneai_preview/compiler.py`
- [Storyboard renderer](https://github.com/nithin0553/cutsceneai-studio/blob/main/preview/src/cutsceneai_preview/rendering.py): `preview/src/cutsceneai_preview/rendering.py`

### Dialogue Pipeline

- [Cue planning](https://github.com/nithin0553/cutsceneai-studio/blob/main/dialogue/src/cutsceneai_dialogue/planning.py): `dialogue/src/cutsceneai_dialogue/planning.py`
- [Audio bundling](https://github.com/nithin0553/cutsceneai-studio/blob/main/dialogue/src/cutsceneai_dialogue/service.py): `dialogue/src/cutsceneai_dialogue/service.py`
- [WAV processing](https://github.com/nithin0553/cutsceneai-studio/blob/main/dialogue/src/cutsceneai_dialogue/audio.py): `dialogue/src/cutsceneai_dialogue/audio.py`
- [Bundle verification](https://github.com/nithin0553/cutsceneai-studio/blob/main/dialogue/src/cutsceneai_dialogue/loading.py): `dialogue/src/cutsceneai_dialogue/loading.py`

### Unreal Export

- [Sequencer compiler](https://github.com/nithin0553/cutsceneai-studio/blob/main/adapters/unreal/src/cutsceneai_unreal/compiler.py): `adapters/unreal/src/cutsceneai_unreal/compiler.py`
- [Engine conversion](https://github.com/nithin0553/cutsceneai-studio/blob/main/adapters/unreal/src/cutsceneai_unreal/conversion.py): `adapters/unreal/src/cutsceneai_unreal/conversion.py`
- [Dialogue importer](https://github.com/nithin0553/cutsceneai-studio/blob/main/adapters/unreal/src/cutsceneai_unreal/dialogue_import.py): `adapters/unreal/src/cutsceneai_unreal/dialogue_import.py`
- [Editor script renderer](https://github.com/nithin0553/cutsceneai-studio/blob/main/adapters/unreal/src/cutsceneai_unreal/rendering.py): `adapters/unreal/src/cutsceneai_unreal/rendering.py`

### Other components

- **Creative user**
- **OpenAI**
- **Speech provider**
- **Unreal Editor**

## Connections

- Creative user → Director API: submits brief
- FastAPI app → CIR validation API: dispatches
- FastAPI app → Director API: dispatches
- FastAPI app → Preview API: dispatches
- FastAPI app → Dialogue API: dispatches
- FastAPI app → Unreal API: dispatches
- CIR validation API → CIR contract: parses project
- CIR validation API → CIR validation: validates
- Director API → Director service: requests generation
- Director service → OpenAI director: generates with
- OpenAI director → OpenAI: requests structured CIR
- Director service → CIR validation: validates result
- Preview API → CIR validation: validates input
- Preview API → Manifest compiler: compiles project
- Preview API → Storyboard renderer: renders manifest
- Manifest compiler → CIR validation: checks project
- Dialogue API → Cue planning: plans cues
- Dialogue API → Audio bundling: builds audio bundle
- Audio bundling → Cue planning: uses cue plan
- Audio bundling → WAV processing: processes WAV
- Audio bundling → Speech provider: synthesizes speech
- Dialogue API → Bundle verification: verifies uploaded bundle
- Unreal API → Sequencer compiler: compiles export
- Sequencer compiler → Manifest compiler: compiles preview data
- Sequencer compiler → Engine conversion: converts engine values
- Unreal API → Dialogue importer: imports dialogue bundle
- Dialogue importer → Bundle verification: verifies bundle
- Unreal API → Editor script renderer: renders import script
- Unreal Editor → Editor script renderer: runs generated script