# 2025btechcsbkavish24308-lab/reelcut-ai architecture

> Architecture diagram of the GitHub repository 2025btechcsbkavish24308-lab/reelcut-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/2025btechcsbkavish24308-lab/reelcut-ai
- Repository: https://github.com/2025btechcsbkavish24308-lab/reelcut-ai

## Overview

#### Purpose and Entry Point

ReelCut AI is an early Python MVP for producing short-form video reels. The operational entry point is `main.py`; no package modules, service layer, or frontend are present in the repository tree. The checked-in `reelcut_jobs/` directory indicates a filesystem-oriented job pipeline rather than a database-backed or web-hosted system.

#### Job Workspace Model

Each render job is isolated under a UUID-named directory beneath `reelcut_jobs/`, for example `reelcut_jobs/065cb998-1e69-4188-afd3-64b34ebdc402/`. These directories retain both source and stage outputs:
- `original.mp4`
- `trimmed.mp4`
- `cropped.mp4`
- `final_reel.mp4`

This layout is the core persistence boundary: media artifacts are passed between processing stages through local files.

#### Video Processing Pipeline

The observable workflow is a linear render pipeline:
1. ingest/store input video as `original.mp4`;
2. select or shorten content into `trimmed.mp4`;
3. reframe output into `cropped.mp4`, likely for vertical short-video dimensions;
4. emit the publishable `final_reel.mp4`.

Representative paths are `reelcut_jobs/9dd3b167-8400-4c98-89f2-34c7b723e30a/original.mp4`, `reelcut_jobs/9dd3b167-8400-4c98-89f2-34c7b723e30a/trimmed.mp4`, and `reelcut_jobs/9dd3b167-8400-4c98-89f2-34c7b723e30a/final_reel.mp4`.

#### Media Boundary and Runtime

The intended runtime is Python, launched directly with `python main.py`. Video transformation depends on MoviePy and/or FFmpeg per the project documentation. FFmpeg is the material external media-processing boundary; it handles encoded MP4 inputs and outputs, while Python coordinates job creation and stage execution.

#### AI Content Capabilities

The product direction includes generated scripts, captions, and TTS narration, but the supplied tree exposes no dedicated source files or stored artifacts for those functions. OpenAI API use is explicitly planned rather than evidenced in the repository. Any future AI integration should remain separate from the deterministic media-render stages and write generated assets into the applicable per-job workspace.

#### Architectural Constraints

There is no visible API server, queue, database, cloud storage integration, authentication boundary, or publishing integration. Job state is inferred from the presence of files within `reelcut_jobs/`; partial artifacts such as `trimmed.mp4` and `cropped.mp4` are likely useful for diagnosing failures or rerunning later render stages. The final contract of the current system is the completed MP4 at paths such as `reelcut_jobs/d293f884-7f21-4bed-bfd2-0b1c1e561b72/final_reel.mp4`.

Main entry points: [`main.py`](https://github.com/2025btechcsbkavish24308-lab/reelcut-ai/blob/main/main.py) (Render orchestration), [`reelcut_jobs/9dd3b167-8400-4c98-89f2-34c7b723e30a/original.mp4`](https://github.com/2025btechcsbkavish24308-lab/reelcut-ai/blob/main/reelcut_jobs/9dd3b167-8400-4c98-89f2-34c7b723e30a/original.mp4) (original.mp4), [`reelcut_jobs/9dd3b167-8400-4c98-89f2-34c7b723e30a/trimmed.mp4`](https://github.com/2025btechcsbkavish24308-lab/reelcut-ai/blob/main/reelcut_jobs/9dd3b167-8400-4c98-89f2-34c7b723e30a/trimmed.mp4) (trimmed.mp4), [`reelcut_jobs/065cb998-1e69-4188-afd3-64b34ebdc402/cropped.mp4`](https://github.com/2025btechcsbkavish24308-lab/reelcut-ai/blob/main/reelcut_jobs/065cb998-1e69-4188-afd3-64b34ebdc402/cropped.mp4) (cropped.mp4)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Python Runtime"]
  node_main["main.py<br/>CLI entry point<br/>[main.py]"]
  node_pipeline["Render orchestration<br/>Python workflow<br/>[main.py]"]
end

subgraph group_workspace["Per-Job Workspace"]
  node_job_workspace[("reelcut_jobs/<br/>filesystem job store")]
  node_job_directory["UUID job directory<br/>job workspace"]
  node_original["original.mp4<br/>input artifact<br/>[original.mp4]"]
  node_trimmed["trimmed.mp4<br/>intermediate artifact<br/>[trimmed.mp4]"]
  node_cropped["cropped.mp4<br/>intermediate artifact<br/>[cropped.mp4]"]
  node_final_reel["final_reel.mp4<br/>final artifact<br/>[final_reel.mp4]"]
end

subgraph group_media["Media Processing"]
  node_ffmpeg{{"FFmpeg / MoviePy<br/>media processing boundary"}}
  node_trim_stage["Trim stage<br/>media transform"]
  node_crop_stage["Crop stage<br/>media transform"]
  node_render_stage["Final render stage<br/>media transform"]
end

node_main -->|"starts"| node_pipeline
node_pipeline -->|"creates job"| node_job_workspace
node_job_workspace -->|"contains"| node_job_directory
node_pipeline -->|"stores input"| node_original
node_original -->|"source"| node_trim_stage
node_trim_stage -->|"writes"| node_trimmed
node_trimmed -->|"source"| node_crop_stage
node_crop_stage -->|"writes"| node_cropped
node_cropped -->|"source"| node_render_stage
node_render_stage -->|"writes"| node_final_reel
node_pipeline -->|"coordinates"| node_ffmpeg
node_ffmpeg -.->|"executes"| node_trim_stage
node_ffmpeg -.->|"executes"| node_crop_stage
node_ffmpeg -.->|"executes"| node_render_stage

click node_main "https://github.com/2025btechcsbkavish24308-lab/reelcut-ai/blob/main/main.py"
click node_original "https://github.com/2025btechcsbkavish24308-lab/reelcut-ai/blob/main/reelcut_jobs/9dd3b167-8400-4c98-89f2-34c7b723e30a/original.mp4"
click node_trimmed "https://github.com/2025btechcsbkavish24308-lab/reelcut-ai/blob/main/reelcut_jobs/9dd3b167-8400-4c98-89f2-34c7b723e30a/trimmed.mp4"
click node_cropped "https://github.com/2025btechcsbkavish24308-lab/reelcut-ai/blob/main/reelcut_jobs/065cb998-1e69-4188-afd3-64b34ebdc402/cropped.mp4"
click node_final_reel "https://github.com/2025btechcsbkavish24308-lab/reelcut-ai/blob/main/reelcut_jobs/9dd3b167-8400-4c98-89f2-34c7b723e30a/final_reel.mp4"
click node_pipeline "https://github.com/2025btechcsbkavish24308-lab/reelcut-ai/blob/main/main.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_main,node_pipeline toneBlue
class node_job_workspace,node_job_directory,node_original,node_trimmed,node_cropped,node_final_reel toneAmber
class node_ffmpeg,node_trim_stage,node_crop_stage,node_render_stage toneMint
```

## Components

### Python Runtime

- [main.py](https://github.com/2025btechcsbkavish24308-lab/reelcut-ai/blob/main/main.py): CLI entry point · Launched directly with python main.py. · `main.py`
- [Render orchestration](https://github.com/2025btechcsbkavish24308-lab/reelcut-ai/blob/main/main.py): Python workflow · Creates jobs and coordinates deterministic media stages. · `main.py`

### Per-Job Workspace

UUID-named directories under reelcut_jobs/ retain pipeline artifacts.

- **reelcut_jobs/**: filesystem job store · The persistence boundary and inferred job state store.
- **UUID job directory**: job workspace · Isolates source media and intermediate render outputs.
- [original.mp4](https://github.com/2025btechcsbkavish24308-lab/reelcut-ai/blob/main/reelcut_jobs/9dd3b167-8400-4c98-89f2-34c7b723e30a/original.mp4): input artifact · `reelcut_jobs/9dd3b167-8400-4c98-89f2-34c7b723e30a/original.mp4`
- [trimmed.mp4](https://github.com/2025btechcsbkavish24308-lab/reelcut-ai/blob/main/reelcut_jobs/9dd3b167-8400-4c98-89f2-34c7b723e30a/trimmed.mp4): intermediate artifact · `reelcut_jobs/9dd3b167-8400-4c98-89f2-34c7b723e30a/trimmed.mp4`
- [cropped.mp4](https://github.com/2025btechcsbkavish24308-lab/reelcut-ai/blob/main/reelcut_jobs/065cb998-1e69-4188-afd3-64b34ebdc402/cropped.mp4): intermediate artifact · Reframed for short-form output. · `reelcut_jobs/065cb998-1e69-4188-afd3-64b34ebdc402/cropped.mp4`
- [final_reel.mp4](https://github.com/2025btechcsbkavish24308-lab/reelcut-ai/blob/main/reelcut_jobs/9dd3b167-8400-4c98-89f2-34c7b723e30a/final_reel.mp4): final artifact · Completed publishable reel contract. · `reelcut_jobs/9dd3b167-8400-4c98-89f2-34c7b723e30a/final_reel.mp4`

### Media Processing

- **FFmpeg / MoviePy**: media processing boundary · Performs encoded MP4 transformations under Python control.
- **Trim stage**: media transform
- **Crop stage**: media transform
- **Final render stage**: media transform

## Connections

- main.py → Render orchestration: starts
- Render orchestration → reelcut_jobs/: creates job
- reelcut_jobs/ → UUID job directory: contains
- Render orchestration → original.mp4: stores input
- original.mp4 → Trim stage: source
- Trim stage → trimmed.mp4: writes
- trimmed.mp4 → Crop stage: source
- Crop stage → cropped.mp4: writes
- cropped.mp4 → Final render stage: source
- Final render stage → final_reel.mp4: writes
- Render orchestration → FFmpeg / MoviePy: coordinates
- FFmpeg / MoviePy → Trim stage: executes
- FFmpeg / MoviePy → Crop stage: executes
- FFmpeg / MoviePy → Final render stage: executes