# saipranav1506/smart-rough-cut architecture

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

- Interactive diagram: https://gitdiagram.com/saipranav1506/smart-rough-cut
- Repository: https://github.com/saipranav1506/smart-rough-cut

## Overview

Smart Rough Cut turns a customer brief and supplied footage into an AI-planned, matched rough cut, then supports editing and export. The API routes orchestrate planning, scene analysis, matching, timeline state, and rendering; the frontend provides processing, editor, and export experiences. The README documents microphone transcription, missing-take handling, and CSV/JSON exports. Some frontend-to-API wiring and unsampled service internals are not shown, so those links are omitted or marked unverified.

Main entry points: [`backend/app/api/routes.py`](https://github.com/saipranav1506/smart-rough-cut/blob/main/backend/app/api/routes.py) (Project API), [`frontend/components/smart-rough-cut-app.tsx`](https://github.com/saipranav1506/smart-rough-cut/blob/main/frontend/components/smart-rough-cut-app.tsx) (App shell), [`backend/app/services/realtime_shot_finder.py`](https://github.com/saipranav1506/smart-rough-cut/blob/main/backend/app/services/realtime_shot_finder.py) (Shot matching), [`backend/app/services/audio_transcriber.py`](https://github.com/saipranav1506/smart-rough-cut/blob/main/backend/app/services/audio_transcriber.py) (Audio transcription)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Editor experience"]
  node_app["App shell"]
  node_processing_ui["Processing view<br/>[page.tsx]"]
  node_editor_ui["Editor workspace"]
  node_export_ui["Export view<br/>[page.tsx]"]
end

subgraph group_api["API and project state"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_routes["Project API<br/>[routes.py]"]
  node_state["Project and timeline state<br/>[routes.py]"]
  node_config["Runtime settings<br/>[config.py]"]
end

subgraph group_planning["Brief and speech"]
  node_planner["Shot planner<br/>[shot_planner.py]"]
  node_transcriber["Audio transcription"]
end

subgraph group_footage["Footage intelligence"]
  node_media_probe["Media metadata<br/>[media_probe.py]"]
  node_scene_detector["Scene and quality analysis<br/>[scene_detector.py]"]
  node_matcher["Shot matching"]
  node_shot_finder["Shot finding<br/>[shot_finder.py]"]
end

subgraph group_output["Timeline and delivery"]
  node_renderer["Video renderer<br/>[renderer.py]"]
end

node_customer(("Editor"))
node_nim{{"NVIDIA NIM"}}
node_speech_service{{"Speech recognition service"}}
node_footage_files["Video footage"]
node_rendered_files["MP4 and decision lists"]

node_customer -->|"uses"| node_app
node_app -.->|"shows processing"| node_processing_ui
node_app -.->|"opens editor"| node_editor_ui
node_app -.->|"opens export"| node_export_ui
node_customer -.->|"speaks brief"| node_transcriber
node_api_app -->|"mounts routes"| node_routes
node_routes -->|"reads and updates"| node_state
node_routes -->|"plans shots"| node_planner
node_routes -->|"matches shots"| node_matcher
node_routes -->|"uses scene cache"| node_scene_detector
node_routes -->|"renders timeline"| node_renderer
node_routes -->|"transcribes audio"| node_transcriber
node_routes -->|"probes footage"| node_media_probe
node_matcher -->|"evaluates scenes"| node_scene_detector
node_planner -->|"requests plan"| node_nim
node_transcriber -->|"recognizes speech"| node_speech_service
node_scene_detector -->|"analyzes frames"| node_footage_files
node_matcher -->|"selects takes"| node_footage_files
node_routes -->|"accepts uploads"| node_footage_files
node_renderer -->|"writes MP4"| node_rendered_files
node_routes -->|"exports JSON and CSV"| node_rendered_files
node_config -->|"configures model"| node_nim

click node_app "https://github.com/saipranav1506/smart-rough-cut/blob/main/frontend/components/smart-rough-cut-app.tsx"
click node_processing_ui "https://github.com/saipranav1506/smart-rough-cut/blob/main/frontend/app/project/%5Bid%5D/processing/page.tsx"
click node_editor_ui "https://github.com/saipranav1506/smart-rough-cut/blob/main/frontend/components/editor-workspace.tsx"
click node_export_ui "https://github.com/saipranav1506/smart-rough-cut/blob/main/frontend/app/project/%5Bid%5D/export/page.tsx"
click node_api_app "https://github.com/saipranav1506/smart-rough-cut/blob/main/backend/app/main.py"
click node_routes "https://github.com/saipranav1506/smart-rough-cut/blob/main/backend/app/api/routes.py"
click node_state "https://github.com/saipranav1506/smart-rough-cut/blob/main/backend/app/api/routes.py"
click node_config "https://github.com/saipranav1506/smart-rough-cut/blob/main/backend/app/core/config.py"
click node_planner "https://github.com/saipranav1506/smart-rough-cut/blob/main/backend/app/services/shot_planner.py"
click node_transcriber "https://github.com/saipranav1506/smart-rough-cut/blob/main/backend/app/services/audio_transcriber.py"
click node_media_probe "https://github.com/saipranav1506/smart-rough-cut/blob/main/backend/app/services/media_probe.py"
click node_scene_detector "https://github.com/saipranav1506/smart-rough-cut/blob/main/backend/app/services/scene_detector.py"
click node_matcher "https://github.com/saipranav1506/smart-rough-cut/blob/main/backend/app/services/realtime_shot_finder.py"
click node_shot_finder "https://github.com/saipranav1506/smart-rough-cut/blob/main/backend/app/services/shot_finder.py"
click node_renderer "https://github.com/saipranav1506/smart-rough-cut/blob/main/backend/app/services/renderer.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_app,node_processing_ui,node_editor_ui,node_export_ui toneBlue
class node_api_app,node_routes,node_state,node_config toneAmber
class node_planner,node_transcriber toneMint
class node_media_probe,node_scene_detector,node_matcher,node_shot_finder toneRose
class node_renderer,node_customer,node_nim,node_speech_service,node_footage_files,node_rendered_files toneIndigo
```

## Components

### Editor experience

- [App shell](https://github.com/saipranav1506/smart-rough-cut/blob/main/frontend/components/smart-rough-cut-app.tsx): `frontend/components/smart-rough-cut-app.tsx`
- [Processing view](https://github.com/saipranav1506/smart-rough-cut/blob/main/frontend/app/project/%5Bid%5D/processing/page.tsx): `frontend/app/project/[id]/processing/page.tsx`
- [Editor workspace](https://github.com/saipranav1506/smart-rough-cut/blob/main/frontend/components/editor-workspace.tsx): `frontend/components/editor-workspace.tsx`
- [Export view](https://github.com/saipranav1506/smart-rough-cut/blob/main/frontend/app/project/%5Bid%5D/export/page.tsx): `frontend/app/project/[id]/export/page.tsx`

### API and project state

- [FastAPI app](https://github.com/saipranav1506/smart-rough-cut/blob/main/backend/app/main.py): `backend/app/main.py`
- [Project API](https://github.com/saipranav1506/smart-rough-cut/blob/main/backend/app/api/routes.py): `backend/app/api/routes.py`
- [Project and timeline state](https://github.com/saipranav1506/smart-rough-cut/blob/main/backend/app/api/routes.py): `backend/app/api/routes.py`
- [Runtime settings](https://github.com/saipranav1506/smart-rough-cut/blob/main/backend/app/core/config.py): `backend/app/core/config.py`

### Brief and speech

- [Shot planner](https://github.com/saipranav1506/smart-rough-cut/blob/main/backend/app/services/shot_planner.py): `backend/app/services/shot_planner.py`
- [Audio transcription](https://github.com/saipranav1506/smart-rough-cut/blob/main/backend/app/services/audio_transcriber.py): `backend/app/services/audio_transcriber.py`

### Footage intelligence

- [Media metadata](https://github.com/saipranav1506/smart-rough-cut/blob/main/backend/app/services/media_probe.py): `backend/app/services/media_probe.py`
- [Scene and quality analysis](https://github.com/saipranav1506/smart-rough-cut/blob/main/backend/app/services/scene_detector.py): `backend/app/services/scene_detector.py`
- [Shot matching](https://github.com/saipranav1506/smart-rough-cut/blob/main/backend/app/services/realtime_shot_finder.py): `backend/app/services/realtime_shot_finder.py`
- [Shot finding](https://github.com/saipranav1506/smart-rough-cut/blob/main/backend/app/services/shot_finder.py): `backend/app/services/shot_finder.py`

### Timeline and delivery

- [Video renderer](https://github.com/saipranav1506/smart-rough-cut/blob/main/backend/app/services/renderer.py): `backend/app/services/renderer.py`

### Other components

- **Editor**
- **NVIDIA NIM**
- **Speech recognition service**
- **Video footage**
- **MP4 and decision lists**

## Connections

- Editor → App shell: uses (evidence: `README.md`)
- App shell → Processing view: shows processing
- App shell → Editor workspace: opens editor
- App shell → Export view: opens export
- Editor → Audio transcription: speaks brief (evidence: `README.md`)
- FastAPI app → Project API: mounts routes (evidence: `backend/app/main.py`)
- Project API → Project and timeline state: reads and updates (evidence: `backend/app/api/routes.py`)
- Project API → Shot planner: plans shots (evidence: `backend/app/api/routes.py`)
- Project API → Shot matching: matches shots (evidence: `backend/app/api/routes.py`)
- Project API → Scene and quality analysis: uses scene cache (evidence: `backend/app/api/routes.py`)
- Project API → Video renderer: renders timeline (evidence: `backend/app/api/routes.py`)
- Project API → Audio transcription: transcribes audio (evidence: `backend/app/api/routes.py`)
- Project API → Media metadata: probes footage (evidence: `backend/app/api/routes.py`)
- Shot matching → Scene and quality analysis: evaluates scenes (evidence: `backend/app/services/realtime_shot_finder.py`)
- Shot planner → NVIDIA NIM: requests plan (evidence: `backend/app/services/shot_planner.py`)
- Audio transcription → Speech recognition service: recognizes speech (evidence: `backend/app/services/audio_transcriber.py`)
- Scene and quality analysis → Video footage: analyzes frames (evidence: `README.md`)
- Shot matching → Video footage: selects takes (evidence: `README.md`)
- Project API → Video footage: accepts uploads (evidence: `backend/app/api/routes.py`)
- Video renderer → MP4 and decision lists: writes MP4 (evidence: `README.md`)
- Project API → MP4 and decision lists: exports JSON and CSV (evidence: `README.md`)
- Runtime settings → NVIDIA NIM: configures model (evidence: `backend/app/core/config.py`)
