OpenCut Administrator & Developer Guide

This guide is the architectural and operational reference for the OpenCut-app/OpenCut repository — the ground-up rewrite of the OpenCut video editor. It is written for developers, architects, and operators who need to understand exactly how this codebase is structured, configured, built, and deployed.

Important

Scope check. At this commit, OpenCut is an early-stage rewrite. The repository is a freshly scaffolded TanStack Start web application: an HTML shell, one route that renders nothing, a Tailwind theme, and a complete shadcn/ui component library. The video editor itself — timeline, preview, export, media handling — does not exist in this repository yet. This guide documents the scaffold honestly and completely. Where a capability is planned but not implemented, it is labeled as such. The currently shipping editor is the classic codebase at opencut-app/opencut-classic.

1. Executive Summary

OpenCut is a free, open-source (MIT-licensed) video editor. The project is rebuilding its application from scratch around a new architecture: a plugin-first design, a shared Rust core targeting desktop/mobile/browser, an Editor API, an MCP server for AI agents, and headless automation.

This repository is the web front-end shell of that rewrite. Its current technical profile:

The single most important architectural fact for an operator is that this is a server-rendered React application deployed as a Cloudflare Worker — there is no separate backend, database, or API tier in this repository.

2. Architecture

2.1 High-level structure

OpenCut (monorepo root)
│
├── Bun workspaces ──── manages apps/*
├── Turborepo ───────── orchestrates dev / build / deploy across apps
│
└── apps/web  (@opencut/web)  ← the only app today
        │
        ├── TanStack Start ──── SSR framework (server entry + routing)
        │     └── TanStack React Router (file-based routes)
        ├── React 19 ────────── UI rendering
        ├── Vite 8 ──────────── dev server + production bundler
        ├── Tailwind v4 ─────── styling
        ├── shadcn/ui ───────── 56 prebuilt components
        └── Cloudflare plugin ─ builds the app as a Worker (wrangler deploy)

2.2 Request flow (production)

Browser → new.opencut.app (Cloudflare edge)
            │
            ▼
        Cloudflare Worker  "opencut-web"
        main = @tanstack/react-start/server-entry
            │
            ▼
        TanStack Start SSR
            │  matches route "/" via routeTree.gen.ts
            ▼
        __root.tsx  (HTML shell: <head> meta/links, TooltipProvider, Scripts)
            │
            ▼
        index.tsx  →  Home()  →  returns null   (no body content yet)
            │
            ▼
        HTML streamed back to browser

The Worker runs with the nodejs_compat compatibility flag, allowing TanStack Start's server entry to use Node.js-style APIs on the Cloudflare runtime.

2.3 The monorepo build pipeline (Turborepo)

turbo.json defines three tasks with their dependency and caching rules:

Because there is only one app today, Turborepo's cross-package orchestration is effectively a pass-through to apps/web, but the pipeline is in place for when the Rust core and additional packages are added.

3. System Requirements

Note

No system-level services are required — no database, message broker, or external API. Local development needs only Bun and a browser.

4. Repository Structure

OpenCut/
├── package.json            Root workspace + Turbo scripts
├── turbo.json              Turborepo task pipeline
├── bunfig.toml             Bun install policy (minimumReleaseAge)
├── bun.lock                Bun lockfile
├── LICENSE                 MIT, © 2026 OpenCut
├── README.md               Project status + roadmap
│
└── apps/
    └── web/                @opencut/web — the web application
        ├── package.json        App deps + scripts
        ├── vite.config.ts      Vite plugin chain
        ├── wrangler.jsonc      Cloudflare Worker config
        ├── tsconfig.json       TypeScript config
        ├── components.json     shadcn/ui config
        ├── .cta.json           Create-TanStack-App metadata
        ├── public/             favicon, robots.txt, manifest.json
        └── src/
            ├── router.tsx          Router factory
            ├── routeTree.gen.ts    Generated route tree (do not edit)
            ├── styles.css          Tailwind + theme tokens
            ├── routes/
            │   ├── __root.tsx      HTML shell + providers + devtools
            │   └── index.tsx       "/" route → renders null
            ├── components/ui/      56 shadcn/ui components
            ├── hooks/
            │   └── use-mobile.ts   useIsMobile() (768px breakpoint)
            └── lib/
                └── utils.ts        cn() class-name helper

Note

56 of the repository's source files are shadcn/ui components under apps/web/src/components/ui/. They are installed and importable but not yet wired into any rendered view. The hand-written application logic is currently confined to __root.tsx, index.tsx, router.tsx, lib/utils.ts, and hooks/use-mobile.ts.

5. Configuration Reference

Every configuration file in the repository, with its exact, source-based values.

5.1 Root package.json

{
  "name": "opencut",
  "private": true,
  "workspaces": ["apps/*"],
  "scripts": {
    "dev": "turbo dev",
    "dev:web": "turbo dev --filter=@opencut/web",
    "build": "turbo build",
    "deploy": "turbo deploy"
  },
  "devDependencies": { "turbo": "latest" },
  "packageManager": "bun@1.3.11"
}

5.2 bunfig.toml — install policy

[install]
minimumReleaseAge = 604800 # 7d

minimumReleaseAge = 604800 seconds (7 days) instructs Bun to refuse any dependency version published in the last week. This is a supply-chain attack mitigation: it creates a quarantine window so that a maliciously published package version is likely to be detected and yanked before it can be installed. See §9 (Security).

5.3 turbo.json

See §2.3 for the task table. The schema is https://turbo.build/schema.json.

5.4 apps/web/package.json — scripts

5.5 apps/web/vite.config.ts — plugin chain

plugins: [
  devtools(),
  cloudflare({ viteEnvironment: { name: 'ssr' } }),
  tailwindcss(),
  tanstackStart(),
  viteReact(),
]

resolve: { tsconfigPaths: true } enables the TypeScript path aliases (#/*, @/*) at build time.

5.6 apps/web/wrangler.jsonc — Cloudflare Worker

{
  "name": "opencut-web",
  "compatibility_date": "2025-09-02",
  "compatibility_flags": ["nodejs_compat"],
  "main": "@tanstack/react-start/server-entry",
  "routes": [
    { "pattern": "new.opencut.app", "custom_domain": true }
  ]
}

Caution

The routes block hard-codes the official production domain. Any fork must change name and remove or replace routes before deploying, or wrangler deploy will attempt to publish to OpenCut's domain (and fail without permission).

5.7 apps/web/tsconfig.json — TypeScript

5.8 apps/web/components.json — shadcn/ui

5.9 apps/web/src/styles.css — theme

The stylesheet composes four imports and defines the theme tokens:

@import 'tailwindcss';
@import "tw-animate-css";
@import "shadcn/tailwind.css";
@import "@fontsource-variable/inter";

@custom-variant dark (&:is(.dark *));

@theme inline {
    --font-heading: 'Playfair Display', serif;
    --font-sans: 'Inter Variable', sans-serif;
    /* ...full shadcn CSS-variable color token set... */
}

5.10 apps/web/public/

Warning

public/manifest.json has not been updated from the scaffold default. Before any public launch it should be rebranded (name, short_name, theme color, icons). Tracked in §13.

6. Routing and the Application Shell

6.1 Router factory — src/router.tsx

export function getRouter() {
  const router = createTanStackRouter({
    routeTree,
    scrollRestoration: true,
    defaultPreload: 'intent',
    defaultPreloadStaleTime: 0,
  })
  return router
}

6.2 Route tree — src/routeTree.gen.ts

Auto-generated by TanStack Router from the files in src/routes/. It registers exactly two routes: the root (__root) and the index (/).

Important

routeTree.gen.ts is machine-generated. Do not edit it by hand — it is regenerated on every build. Add routes by creating files under src/routes/.

6.3 Root shell — src/routes/__root.tsx

The root route defines the HTML document: <head> metadata (charset, viewport, title), the favicon link, Google Fonts preconnect + the Playfair Display stylesheet, and the app CSS import. The body wraps all child routes in a TooltipProvider and mounts TanStackDevtools (with the Router DevTools panel) plus the framework Scripts component.

Note

The document <title> is hard-coded to "OpenCut rewrite — beta.opencut.app". Note that this references beta.opencut.app, while the deployment target in wrangler.jsonc and the README is new.opencut.app — a naming inconsistency flagged in §13.

Note

TanStackDevtools is mounted unconditionally in the shell. In a typical production build it should be gated behind a development-only check; verify this before public launch (§13).

6.4 Index route — src/routes/index.tsx

export const Route = createFileRoute('/')({ component: Home })

function Home() {
  return null
}

The home page renders null. This is the placeholder where the editor UI will be mounted. There is no editor component in this repository yet.

7. The UI Component Layer

The repository ships a full shadcn/ui kit (56 components, see §4 / User Guide §5) configured with the base-mira style, the neutral base color, CSS-variable theming, and the Hugeicons icon set. Components are built on Base UI (@base-ui/react) and Radix UI primitives.

Supporting utilities:

A large set of interaction libraries is already declared as dependencies, ready for the editor build: react-hook-form + zod + @hookform/resolvers (forms/validation), date-fns + react-day-picker (dates), embla-carousel-react (carousels), cmdk (command palette), sonner (toasts), vaul (drawers), recharts (charts), react-resizable-panels (resizable layout — a likely editor-panel primitive), next-themes (theme switching), and input-otp.

Note

These libraries are installed but not yet consumed by any rendered code. Treat the dependency list as a statement of intent for the editor UI, not as currently active features.

8. Build and Deployment Operations

8.1 Local development

bun install          # from repo root
bun run dev          # all apps via Turborepo
# or: bun run dev:web (web only)

Vite serves on http://localhost:5173.

8.2 Production build

# repo root
bun run build        # turbo build → vite build in apps/web

Outputs land in .output/** and/or dist/** (per turbo.json).

8.3 Deploy to Cloudflare

# from apps/web
wrangler login        # one-time auth
bun run deploy        # vite build && wrangler deploy

This publishes the Worker opencut-web and binds it to new.opencut.app.

8.4 Inspecting a running deployment

# Stream live logs from the deployed Worker
wrangler tail opencut-web

Tip

Cloudflare retains deployment history per Worker. To roll back, redeploy from a known-good commit or promote a previous version from the Cloudflare dashboard's Worker deployments view.

9. Security Analysis

This is a static, server-rendered shell with no user input, authentication, data storage, or secrets — so the present attack surface is small. The relevant points are about supply-chain posture and what will need hardening as the editor grows.

9.1 Supply-chain controls (present)

Tip

The minimumReleaseAge policy is a strong, low-cost supply-chain control. Keep it in place. If a build fails because a needed version is too new, prefer waiting out the window over lowering the threshold.

9.2 Runtime posture (present)

• No secrets / environment variables. The repository consumes no .env files and .cta.json declares no env var values. There are no credentials to leak in this repository.
• No authentication or authorization. There is no login, session, or user model — appropriate for a shell, but the editor's eventual collaboration/cloud features will introduce this surface.
• nodejs_compat enabled. This widens the Worker's available APIs; review what the editor build actually uses so the compatibility surface stays minimal.
• Permissive robots.txt. All crawlers are allowed (Disallow: empty), which is fine for a public marketing/editor site.

9.3 Future trust boundaries (planned, not yet present)

The roadmap (§12) introduces the project's most significant future security surfaces:

Warning

First-class third-party plugins and an MCP server for AI agents are planned. Both execute or are driven by untrusted external code/instructions. When these land, they will become the primary trust boundaries and will require sandboxing, capability scoping, and an explicit permission model. None of this exists in the current repository — but it should be designed in from the start of the plugin architecture.

9.4 Development tooling exposure

TanStackDevtools is mounted in the root shell (§6.3). DevTools panels can expose router internals and should not ship enabled in production. Confirm the build strips or gates them before public launch.

10. Code Quality and Conventions

The codebase is small, idiomatic, and consistent with current TanStack Start + shadcn scaffolding conventions. There is little custom logic to assess yet.

11. Testing Strategy

The toolchain is configured for testing but no tests exist yet.

Important

bun run test succeeds vacuously today because there are zero test files. As editor logic lands, establish test coverage from the first feature — the harness is already in place, so there is no setup cost.

12. Roadmap

From the project README, the rewrite is targeting:

• An Editor API — programmatic control of the editor.
• First-class third-party plugins — enabled by a plugin-first architecture.
• One codebase for desktop, mobile, and browser — via a shared Rust core.
• An MCP server — to let AI agents operate the editor.
• Headless mode — automation and batch rendering.
• A scripting tab — in-editor scripting.

Note

None of the above is implemented in this repository. The Rust core, plugin system, MCP server, headless mode, and scripting tab are design goals. This repository is the web shell those features will attach to.

13. Improvements and Known Gaps

Source-based items worth addressing, derived from the current state of the repository.

• [ ] Rebrand public/manifest.json — it still carries the scaffold defaults ("TanStack App" / "Create TanStack App Sample"). Set OpenCut's name, short_name, theme color, and icons.
• [ ] Resolve the domain-name inconsistency — __root.tsx hard-codes the <title> "OpenCut rewrite — beta.opencut.app", while wrangler.jsonc and the README use new.opencut.app. Pick one and align them.
• [ ] Gate TanStackDevtools to development — it is mounted unconditionally in the root shell (§6.3). Strip or guard it for production builds.
• [ ] Add tests — the Vitest/jsdom/Testing-Library harness is ready but unused (§11). Begin coverage with the first editor feature.
• [ ] Build the editor — the home route renders null. This is the central piece of work; everything else is foundation.
• [ ] Design plugin/MCP trust boundaries up front — the planned plugin system and MCP server are the project's future primary security surfaces (§9.3). Bake sandboxing and a permission model into the architecture rather than retrofitting them.

Note

The community issues filed against OpenCut (export memory usage, playback stutter, audio/text bugs) pertain to the classic editor at opencut-classic, not to this rewrite repository, which contains none of that code. They are not actionable here.

14. Quick Reference

Commands

Key files

Facts