# toannguyen-exe/autocut architecture

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

- Interactive diagram: https://gitdiagram.com/toannguyen-exe/autocut
- Repository: https://github.com/toannguyen-exe/autocut

## Overview

AutoCut is a video-editing studio for turning lecture recordings into transcript-based sections, topics, and exportable clips. The user workflow runs from the studio interface through video APIs to transcript/segment operations, then cutting and export; persistence and cloud storage support those operations. A separate Python AI workflow transcribes and refines speech. The README is empty, and frontend-to-backend wiring is not shown in the sampled files, so that connection is marked unverified; unsampled UI capabilities are represented by their source paths.

Main entry points: [`frontend/src/app/page.tsx`](https://github.com/toannguyen-exe/autocut/blob/main/frontend/src/app/page.tsx) (Studio workspace), [`backend/src/main/java/com/autocut/controller/VideoController.java`](https://github.com/toannguyen-exe/autocut/blob/main/backend/src/main/java/com/autocut/controller/VideoController.java) (Video endpoints), [`backend/ai/cli.py`](https://github.com/toannguyen-exe/autocut/blob/main/backend/ai/cli.py) (AI processing CLI), [`backend/src/main/java/com/autocut/repository/VideoRepository.java`](https://github.com/toannguyen-exe/autocut/blob/main/backend/src/main/java/com/autocut/repository/VideoRepository.java) (Video repositories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_studio["Studio interface"]
  node_studio_ui["Studio workspace<br/>[page.tsx]"]
  node_video_library["Video library"]
  node_transcript_views["Transcript and scenes"]
  node_timeline["Studio timeline<br/>[StudioTimeline.tsx]"]
  node_review["Segment review<br/>[ReviewTable.tsx]"]
  node_preview["Video preview"]
  node_export_ui["Export progress"]
  node_assistant["AI assistant"]
  node_frontend_api["Frontend API client<br/>[api.ts]"]
  node_chat_routes["Assistant chat routes<br/>[route.ts]"]
end

subgraph group_api["Video API"]
  node_video_controller["Video endpoints"]
end

subgraph group_domain["Transcript and segmentation"]
  node_cut_points["Cut-point analysis"]
  node_segment_persistence["Segment persistence"]
  node_domain_models["Transcript and segment models<br/>[Models.java]"]
  node_repositories["Video repositories"]
  node_entities["Video and transcript records<br/>[VideoEntity.java]"]
end

subgraph group_media["Cutting and storage"]
  node_batch_cut["Batch cut jobs"]
  node_video_cutter["Video cutter<br/>[VideoCutter.java]"]
  node_cloud_storage["R2 object storage"]
end

subgraph group_ai["AI transcription"]
  node_ai_cli["AI processing CLI<br/>[cli.py]"]
  node_whisper["Whisper transcription<br/>[whisper_service.py]"]
  node_groq["Groq transcription<br/>[groq_service.py]"]
  node_refiner["Transcript refinement"]
  node_post_processor["Transcript cleanup<br/>[post_processor.py]"]
  node_ai_models["AI transcript models<br/>[models.py]"]
  node_gemini["Gemini transcription"]
end

node_user(("Studio user"))
node_database[("Application database")]
node_r2_service[("Cloudflare R2")]

node_user -->|"uses"| node_studio_ui
node_studio_ui -->|"presents"| node_video_library
node_studio_ui -->|"presents"| node_transcript_views
node_studio_ui -->|"presents"| node_timeline
node_studio_ui -->|"presents"| node_review
node_studio_ui -->|"presents"| node_preview
node_studio_ui -->|"presents"| node_export_ui
node_studio_ui -.->|"requests data"| node_frontend_api
node_frontend_api -.->|"calls endpoints"| node_video_controller
node_assistant -.->|"uses"| node_chat_routes
node_video_controller -->|"calls"| node_cut_points
node_video_controller -->|"persists segments"| node_segment_persistence
node_video_controller -->|"starts cut jobs"| node_batch_cut
node_video_controller -->|"uses DTOs"| node_domain_models
node_video_controller -->|"reads videos"| node_repositories
node_segment_persistence -->|"reads and writes"| node_repositories
node_repositories -->|"stores"| node_entities
node_repositories -.->|"queries"| node_database
node_batch_cut -->|"cuts clips"| node_video_cutter
node_batch_cut -->|"uploads exports"| node_cloud_storage
node_cloud_storage -->|"stores objects"| node_r2_service
node_ai_cli -->|"transcribes audio"| node_whisper
node_ai_cli -->|"refines transcript"| node_refiner
node_ai_cli -->|"cleans transcript"| node_post_processor
node_whisper -->|"uses cloud fallback"| node_groq
node_refiner -->|"uses cleanup"| node_post_processor
node_refiner -->|"uses models"| node_ai_models
node_ai_cli -->|"supports transcription"| node_gemini

click node_studio_ui "https://github.com/toannguyen-exe/autocut/blob/main/frontend/src/app/page.tsx"
click node_video_library "https://github.com/toannguyen-exe/autocut/blob/main/frontend/src/components/VideoLibraryColumn.tsx"
click node_transcript_views "https://github.com/toannguyen-exe/autocut/blob/main/frontend/src/components/TranscriptScenesPanel.tsx"
click node_timeline "https://github.com/toannguyen-exe/autocut/blob/main/frontend/src/components/StudioTimeline.tsx"
click node_review "https://github.com/toannguyen-exe/autocut/blob/main/frontend/src/components/ReviewTable.tsx"
click node_preview "https://github.com/toannguyen-exe/autocut/blob/main/frontend/src/components/VideoPlayerPreview.tsx"
click node_export_ui "https://github.com/toannguyen-exe/autocut/blob/main/frontend/src/components/ExportProgressModal.tsx"
click node_assistant "https://github.com/toannguyen-exe/autocut/blob/main/frontend/src/components/AiAssistantChatPanel.tsx"
click node_frontend_api "https://github.com/toannguyen-exe/autocut/blob/main/frontend/src/lib/api.ts"
click node_video_controller "https://github.com/toannguyen-exe/autocut/blob/main/backend/src/main/java/com/autocut/controller/VideoController.java"
click node_cut_points "https://github.com/toannguyen-exe/autocut/blob/main/backend/src/main/java/com/autocut/service/CutPointService.java"
click node_segment_persistence "https://github.com/toannguyen-exe/autocut/blob/main/backend/src/main/java/com/autocut/service/SegmentPersistenceService.java"
click node_domain_models "https://github.com/toannguyen-exe/autocut/blob/main/backend/src/main/java/com/autocut/dto/Models.java"
click node_repositories "https://github.com/toannguyen-exe/autocut/blob/main/backend/src/main/java/com/autocut/repository/VideoRepository.java"
click node_entities "https://github.com/toannguyen-exe/autocut/blob/main/backend/src/main/java/com/autocut/entity/VideoEntity.java"
click node_batch_cut "https://github.com/toannguyen-exe/autocut/blob/main/backend/src/main/java/com/autocut/service/BatchVideoCutService.java"
click node_video_cutter "https://github.com/toannguyen-exe/autocut/blob/main/backend/src/main/java/com/autocut/video/VideoCutter.java"
click node_cloud_storage "https://github.com/toannguyen-exe/autocut/blob/main/backend/src/main/java/com/autocut/service/CloudflareR2Service.java"
click node_ai_cli "https://github.com/toannguyen-exe/autocut/blob/main/backend/ai/cli.py"
click node_whisper "https://github.com/toannguyen-exe/autocut/blob/main/backend/ai/whisper_service.py"
click node_groq "https://github.com/toannguyen-exe/autocut/blob/main/backend/ai/groq_service.py"
click node_refiner "https://github.com/toannguyen-exe/autocut/blob/main/backend/ai/transcript_refiner.py"
click node_post_processor "https://github.com/toannguyen-exe/autocut/blob/main/backend/ai/post_processor.py"
click node_ai_models "https://github.com/toannguyen-exe/autocut/blob/main/backend/ai/models.py"
click node_gemini "https://github.com/toannguyen-exe/autocut/blob/main/backend/ai/gemini_transcriber.py"
click node_chat_routes "https://github.com/toannguyen-exe/autocut/blob/main/frontend/src/app/api/chat/route.ts"

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_studio_ui,node_video_library,node_transcript_views,node_timeline,node_review,node_preview,node_export_ui,node_assistant,node_frontend_api,node_chat_routes,node_user toneBlue
class node_video_controller,node_database,node_r2_service toneAmber
class node_cut_points,node_segment_persistence,node_domain_models,node_repositories,node_entities toneMint
class node_batch_cut,node_video_cutter,node_cloud_storage toneRose
class node_ai_cli,node_whisper,node_groq,node_refiner,node_post_processor,node_ai_models,node_gemini toneIndigo
```

## Components

### Studio interface

- [Studio workspace](https://github.com/toannguyen-exe/autocut/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Video library](https://github.com/toannguyen-exe/autocut/blob/main/frontend/src/components/VideoLibraryColumn.tsx): `frontend/src/components/VideoLibraryColumn.tsx`
- [Transcript and scenes](https://github.com/toannguyen-exe/autocut/blob/main/frontend/src/components/TranscriptScenesPanel.tsx): `frontend/src/components/TranscriptScenesPanel.tsx`
- [Studio timeline](https://github.com/toannguyen-exe/autocut/blob/main/frontend/src/components/StudioTimeline.tsx): `frontend/src/components/StudioTimeline.tsx`
- [Segment review](https://github.com/toannguyen-exe/autocut/blob/main/frontend/src/components/ReviewTable.tsx): `frontend/src/components/ReviewTable.tsx`
- [Video preview](https://github.com/toannguyen-exe/autocut/blob/main/frontend/src/components/VideoPlayerPreview.tsx): `frontend/src/components/VideoPlayerPreview.tsx`
- [Export progress](https://github.com/toannguyen-exe/autocut/blob/main/frontend/src/components/ExportProgressModal.tsx): `frontend/src/components/ExportProgressModal.tsx`
- [AI assistant](https://github.com/toannguyen-exe/autocut/blob/main/frontend/src/components/AiAssistantChatPanel.tsx): `frontend/src/components/AiAssistantChatPanel.tsx`
- [Frontend API client](https://github.com/toannguyen-exe/autocut/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Assistant chat routes](https://github.com/toannguyen-exe/autocut/blob/main/frontend/src/app/api/chat/route.ts): `frontend/src/app/api/chat/route.ts`

### Video API

- [Video endpoints](https://github.com/toannguyen-exe/autocut/blob/main/backend/src/main/java/com/autocut/controller/VideoController.java): `backend/src/main/java/com/autocut/controller/VideoController.java`

### Transcript and segmentation

- [Cut-point analysis](https://github.com/toannguyen-exe/autocut/blob/main/backend/src/main/java/com/autocut/service/CutPointService.java): `backend/src/main/java/com/autocut/service/CutPointService.java`
- [Segment persistence](https://github.com/toannguyen-exe/autocut/blob/main/backend/src/main/java/com/autocut/service/SegmentPersistenceService.java): `backend/src/main/java/com/autocut/service/SegmentPersistenceService.java`
- [Transcript and segment models](https://github.com/toannguyen-exe/autocut/blob/main/backend/src/main/java/com/autocut/dto/Models.java): `backend/src/main/java/com/autocut/dto/Models.java`
- [Video repositories](https://github.com/toannguyen-exe/autocut/blob/main/backend/src/main/java/com/autocut/repository/VideoRepository.java): `backend/src/main/java/com/autocut/repository/VideoRepository.java`
- [Video and transcript records](https://github.com/toannguyen-exe/autocut/blob/main/backend/src/main/java/com/autocut/entity/VideoEntity.java): `backend/src/main/java/com/autocut/entity/VideoEntity.java`

### Cutting and storage

- [Batch cut jobs](https://github.com/toannguyen-exe/autocut/blob/main/backend/src/main/java/com/autocut/service/BatchVideoCutService.java): `backend/src/main/java/com/autocut/service/BatchVideoCutService.java`
- [Video cutter](https://github.com/toannguyen-exe/autocut/blob/main/backend/src/main/java/com/autocut/video/VideoCutter.java): `backend/src/main/java/com/autocut/video/VideoCutter.java`
- [R2 object storage](https://github.com/toannguyen-exe/autocut/blob/main/backend/src/main/java/com/autocut/service/CloudflareR2Service.java): `backend/src/main/java/com/autocut/service/CloudflareR2Service.java`

### AI transcription

- [AI processing CLI](https://github.com/toannguyen-exe/autocut/blob/main/backend/ai/cli.py): `backend/ai/cli.py`
- [Whisper transcription](https://github.com/toannguyen-exe/autocut/blob/main/backend/ai/whisper_service.py): `backend/ai/whisper_service.py`
- [Groq transcription](https://github.com/toannguyen-exe/autocut/blob/main/backend/ai/groq_service.py): `backend/ai/groq_service.py`
- [Transcript refinement](https://github.com/toannguyen-exe/autocut/blob/main/backend/ai/transcript_refiner.py): `backend/ai/transcript_refiner.py`
- [Transcript cleanup](https://github.com/toannguyen-exe/autocut/blob/main/backend/ai/post_processor.py): `backend/ai/post_processor.py`
- [AI transcript models](https://github.com/toannguyen-exe/autocut/blob/main/backend/ai/models.py): `backend/ai/models.py`
- [Gemini transcription](https://github.com/toannguyen-exe/autocut/blob/main/backend/ai/gemini_transcriber.py): `backend/ai/gemini_transcriber.py`

### Other components

- **Studio user**
- **Application database**
- **Cloudflare R2**

## Connections

- Studio user → Studio workspace: uses
- Studio workspace → Video library: presents
- Studio workspace → Transcript and scenes: presents
- Studio workspace → Studio timeline: presents
- Studio workspace → Segment review: presents
- Studio workspace → Video preview: presents
- Studio workspace → Export progress: presents
- Studio workspace → Frontend API client: requests data
- Frontend API client → Video endpoints: calls endpoints
- AI assistant → Assistant chat routes: uses
- Video endpoints → Cut-point analysis: calls (evidence: `backend/src/main/java/com/autocut/controller/VideoController.java`)
- Video endpoints → Segment persistence: persists segments (evidence: `backend/src/main/java/com/autocut/controller/VideoController.java`)
- Video endpoints → Batch cut jobs: starts cut jobs (evidence: `backend/src/main/java/com/autocut/controller/VideoController.java`)
- Video endpoints → Transcript and segment models: uses DTOs (evidence: `backend/src/main/java/com/autocut/controller/VideoController.java`)
- Video endpoints → Video repositories: reads videos (evidence: `backend/src/main/java/com/autocut/controller/VideoController.java`)
- Segment persistence → Video repositories: reads and writes (evidence: `backend/src/main/java/com/autocut/service/SegmentPersistenceService.java`)
- Video repositories → Video and transcript records: stores (evidence: `backend/src/main/java/com/autocut/repository/VideoRepository.java`)
- Video repositories → Application database: queries
- Batch cut jobs → Video cutter: cuts clips (evidence: `backend/src/main/java/com/autocut/service/BatchVideoCutService.java`)
- Batch cut jobs → R2 object storage: uploads exports (evidence: `backend/src/main/java/com/autocut/service/BatchVideoCutService.java`)
- R2 object storage → Cloudflare R2: stores objects (evidence: `backend/src/main/java/com/autocut/service/CloudflareR2Service.java`)
- AI processing CLI → Whisper transcription: transcribes audio (evidence: `backend/ai/cli.py`)
- AI processing CLI → Transcript refinement: refines transcript (evidence: `backend/ai/cli.py`)
- AI processing CLI → Transcript cleanup: cleans transcript (evidence: `backend/ai/cli.py`)
- Whisper transcription → Groq transcription: uses cloud fallback (evidence: `backend/ai/whisper_service.py`)
- Transcript refinement → Transcript cleanup: uses cleanup (evidence: `backend/ai/transcript_refiner.py`)
- Transcript refinement → AI transcript models: uses models (evidence: `backend/ai/transcript_refiner.py`)
- AI processing CLI → Gemini transcription: supports transcription (evidence: `backend/ai/cli.py`)
