# acm-projects/cascade architecture

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

- Interactive diagram: https://gitdiagram.com/acm-projects/cascade
- Repository: https://github.com/acm-projects/cascade

## Overview

Cascade is a video-to-clips product with project management, AI research, a nondestructive editor, and export/publishing features. The main workflow is upload and describe a video, generate searchable clips, refine them in the editor, then export or publish. AI Studio supports creating and revising generations from project media; video search and trends research are additional capabilities. The React app is the current interface, with FastAPI services behind it. The map uses README workflow statements and sampled source references; unsampled feature internals and some frontend-to-API wiring are not asserted.

Main entry points: [`frontend/src/App.jsx`](https://github.com/acm-projects/cascade/blob/main/frontend/src/App.jsx) (Application routes), [`backend/routers/clips.py`](https://github.com/acm-projects/cascade/blob/main/backend/routers/clips.py) (Upload and generation routes), [`backend/editor/routes.py`](https://github.com/acm-projects/cascade/blob/main/backend/editor/routes.py) (Editor routes), [`backend/agent/website.py`](https://github.com/acm-projects/cascade/blob/main/backend/agent/website.py) (Clip selection agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React application"]
  node_app["Application routes<br/>[App.jsx]"]
  node_studio_ui["AI Studio<br/>[StudioPage.jsx]"]
  node_editor_ui["Editor<br/>[EditorPage.jsx]"]
  node_export_ui["Export<br/>[ExportPage.jsx]"]
  node_projects_ui["Projects<br/>[ProjectsPage.jsx]"]
end

subgraph group_generation["Clip generation"]
  node_upload_routes["Upload and generation routes<br/>[clips.py]"]
  node_job_state["Jobs and progress<br/>[jobs.py]"]
  node_clip_agent["Clip selection agent<br/>[website.py]"]
  node_transcription["Speech transcription<br/>[transcribe.py]"]
  node_media_storage["Media storage<br/>[storage.py]"]
end

subgraph group_research["Research and discovery"]
  node_video_search["Search and clip matching<br/>[router.py]"]
  node_research_agent["Research agent<br/>[research.py]"]
  node_trends["Trend analysis<br/>[pipeline.py]"]
  node_studio_service["Studio sessions<br/>[studio.py]"]
end

subgraph group_editing["Editing and rendering"]
  node_editor_routes["Editor routes<br/>[routes.py]"]
  node_editor_render["Timeline rendering<br/>[render.py]"]
  node_editor_media["Editor media access<br/>[media_routes.py]"]
  node_broll["B-roll assets<br/>[broll.py]"]
end

subgraph group_delivery["Projects and delivery"]
  node_project_store[("Project records<br/>[projects_store.py]")]
  node_publishing["Social publishing"]
end

node_user(("Creator"))
node_deepgram{{"Deepgram"}}
node_ai_provider{{"AI provider"}}
node_object_store[("S3 storage")]

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_projects_ui
node_app -->|"routes to"| node_studio_ui
node_app -->|"routes to"| node_editor_ui
node_app -->|"routes to"| node_export_ui
node_user -->|"uploads video"| node_upload_routes
node_upload_routes -->|"tracks job"| node_job_state
node_upload_routes -->|"selects clips"| node_clip_agent
node_clip_agent -->|"transcribes media"| node_transcription
node_upload_routes -->|"stores media"| node_media_storage
node_transcription -->|"transcribes with"| node_deepgram
node_clip_agent -->|"uses configurable AI"| node_ai_provider
node_media_storage -->|"uploads media"| node_object_store
node_user -->|"searches video"| node_video_search
node_user -->|"creates generations"| node_studio_ui
node_studio_ui -.->|"uses sessions"| node_studio_service
node_user -->|"requests research"| node_research_agent
node_user -->|"explores trends"| node_trends
node_editor_ui -->|"edits clips"| node_editor_routes
node_editor_routes -->|"renders edits"| node_editor_render
node_editor_routes -->|"serves media"| node_editor_media
node_editor_routes -->|"uses B-roll"| node_broll
node_projects_ui -->|"manages projects"| node_project_store
node_export_ui -->|"publishes clips"| node_publishing

click node_app "https://github.com/acm-projects/cascade/blob/main/frontend/src/App.jsx"
click node_studio_ui "https://github.com/acm-projects/cascade/blob/main/frontend/src/pages/StudioPage.jsx"
click node_editor_ui "https://github.com/acm-projects/cascade/blob/main/frontend/src/pages/EditorPage.jsx"
click node_export_ui "https://github.com/acm-projects/cascade/blob/main/frontend/src/pages/ExportPage.jsx"
click node_projects_ui "https://github.com/acm-projects/cascade/blob/main/frontend/src/pages/ProjectsPage.jsx"
click node_upload_routes "https://github.com/acm-projects/cascade/blob/main/backend/routers/clips.py"
click node_job_state "https://github.com/acm-projects/cascade/blob/main/backend/core/jobs.py"
click node_clip_agent "https://github.com/acm-projects/cascade/blob/main/backend/agent/website.py"
click node_transcription "https://github.com/acm-projects/cascade/blob/main/backend/cascade_stt/transcribe.py"
click node_media_storage "https://github.com/acm-projects/cascade/blob/main/backend/core/storage.py"
click node_video_search "https://github.com/acm-projects/cascade/blob/main/backend/video_search/router.py"
click node_research_agent "https://github.com/acm-projects/cascade/blob/main/backend/agent/research.py"
click node_trends "https://github.com/acm-projects/cascade/blob/main/backend/trends/pipeline.py"
click node_studio_service "https://github.com/acm-projects/cascade/blob/main/backend/studio.py"
click node_editor_routes "https://github.com/acm-projects/cascade/blob/main/backend/editor/routes.py"
click node_editor_render "https://github.com/acm-projects/cascade/blob/main/backend/editor/render.py"
click node_editor_media "https://github.com/acm-projects/cascade/blob/main/backend/editor/media_routes.py"
click node_broll "https://github.com/acm-projects/cascade/blob/main/backend/broll.py"
click node_project_store "https://github.com/acm-projects/cascade/blob/main/backend/services/projects_store.py"
click node_publishing "https://github.com/acm-projects/cascade/blob/main/backend/publishing_providers.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_studio_ui,node_editor_ui,node_export_ui,node_projects_ui toneBlue
class node_upload_routes,node_job_state,node_clip_agent,node_transcription,node_media_storage,node_object_store toneAmber
class node_video_search,node_research_agent,node_trends,node_studio_service toneMint
class node_editor_routes,node_editor_render,node_editor_media,node_broll toneRose
class node_project_store,node_publishing,node_user,node_deepgram,node_ai_provider toneIndigo
```

## Components

### React application

- [Application routes](https://github.com/acm-projects/cascade/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [AI Studio](https://github.com/acm-projects/cascade/blob/main/frontend/src/pages/StudioPage.jsx): `frontend/src/pages/StudioPage.jsx`
- [Editor](https://github.com/acm-projects/cascade/blob/main/frontend/src/pages/EditorPage.jsx): `frontend/src/pages/EditorPage.jsx`
- [Export](https://github.com/acm-projects/cascade/blob/main/frontend/src/pages/ExportPage.jsx): `frontend/src/pages/ExportPage.jsx`
- [Projects](https://github.com/acm-projects/cascade/blob/main/frontend/src/pages/ProjectsPage.jsx): `frontend/src/pages/ProjectsPage.jsx`

### Clip generation

- [Upload and generation routes](https://github.com/acm-projects/cascade/blob/main/backend/routers/clips.py): `backend/routers/clips.py`
- [Jobs and progress](https://github.com/acm-projects/cascade/blob/main/backend/core/jobs.py): `backend/core/jobs.py`
- [Clip selection agent](https://github.com/acm-projects/cascade/blob/main/backend/agent/website.py): `backend/agent/website.py`
- [Speech transcription](https://github.com/acm-projects/cascade/blob/main/backend/cascade_stt/transcribe.py): `backend/cascade_stt/transcribe.py`
- [Media storage](https://github.com/acm-projects/cascade/blob/main/backend/core/storage.py): `backend/core/storage.py`

### Research and discovery

- [Search and clip matching](https://github.com/acm-projects/cascade/blob/main/backend/video_search/router.py): `backend/video_search/router.py`
- [Research agent](https://github.com/acm-projects/cascade/blob/main/backend/agent/research.py): `backend/agent/research.py`
- [Trend analysis](https://github.com/acm-projects/cascade/blob/main/backend/trends/pipeline.py): `backend/trends/pipeline.py`
- [Studio sessions](https://github.com/acm-projects/cascade/blob/main/backend/studio.py): `backend/studio.py`

### Editing and rendering

- [Editor routes](https://github.com/acm-projects/cascade/blob/main/backend/editor/routes.py): `backend/editor/routes.py`
- [Timeline rendering](https://github.com/acm-projects/cascade/blob/main/backend/editor/render.py): `backend/editor/render.py`
- [Editor media access](https://github.com/acm-projects/cascade/blob/main/backend/editor/media_routes.py): `backend/editor/media_routes.py`
- [B-roll assets](https://github.com/acm-projects/cascade/blob/main/backend/broll.py): `backend/broll.py`

### Projects and delivery

- [Project records](https://github.com/acm-projects/cascade/blob/main/backend/services/projects_store.py): `backend/services/projects_store.py`
- [Social publishing](https://github.com/acm-projects/cascade/blob/main/backend/publishing_providers.py): `backend/publishing_providers.py`

### Other components

- **Creator**
- **Deepgram**
- **AI provider**
- **S3 storage**

## Connections

- Creator → Application routes: uses (evidence: `README.md`)
- Application routes → Projects: routes to (evidence: `frontend/src/App.jsx`)
- Application routes → AI Studio: routes to (evidence: `frontend/src/App.jsx`)
- Application routes → Editor: routes to (evidence: `frontend/src/App.jsx`)
- Application routes → Export: routes to (evidence: `frontend/src/App.jsx`)
- Creator → Upload and generation routes: uploads video (evidence: `README.md`)
- Upload and generation routes → Jobs and progress: tracks job (evidence: `backend/routers/clips.py`)
- Upload and generation routes → Clip selection agent: selects clips (evidence: `backend/routers/clips.py`)
- Clip selection agent → Speech transcription: transcribes media
- Upload and generation routes → Media storage: stores media (evidence: `backend/routers/clips.py`)
- Speech transcription → Deepgram: transcribes with (evidence: `README.md`)
- Clip selection agent → AI provider: uses configurable AI (evidence: `README.md`)
- Media storage → S3 storage: uploads media (evidence: `backend/core/storage.py`)
- Creator → Search and clip matching: searches video (evidence: `README.md`)
- Creator → AI Studio: creates generations (evidence: `README.md`)
- AI Studio → Studio sessions: uses sessions
- Creator → Research agent: requests research (evidence: `README.md`)
- Creator → Trend analysis: explores trends (evidence: `README.md`)
- Editor → Editor routes: edits clips (evidence: `README.md`)
- Editor routes → Timeline rendering: renders edits (evidence: `backend/editor/routes.py`)
- Editor routes → Editor media access: serves media (evidence: `backend/editor/routes.py`)
- Editor routes → B-roll assets: uses B-roll
- Projects → Project records: manages projects (evidence: `README.md`)
- Export → Social publishing: publishes clips (evidence: `README.md`)
