# phangb/opencut architecture

> Architecture diagram of the GitHub repository phangb/opencut, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/phangb/opencut
- Repository: https://github.com/phangb/opencut

## Overview

Step 1: Identify the project type and purpose
- This is a full-stack, open-source video editor (“OpenCut”) built as a monorepo.
- The core application lives in apps/web (Next.js 13+ with React and TypeScript), offering timeline-based, multi-track video editing via ffmpeg.wasm in the browser.
- Two local packages support it: an authentication library (packages/auth) and a database layer (packages/db).

Step 2: Analyze the file structure
- Top-level: monorepo with Turborepo (turbo.json), CI/CD (GitHub Actions .github/workflows/bun-ci.yml), Docker Compose, Netlify/Vercel configs.
- apps/web: Next.js App Router under src/app, UI components under src/components, custom React hooks, utility code, Zustand stores, Drizzle ORM config, migrations, public assets (ffmpeg.wasm). API routes for auth, health, waitlist.
- packages/auth: client and server modules for handling signup/login, token management.
- packages/db: Drizzle ORM schema, config, and SQL migrations for Postgres.
- docker-compose.yaml: defines Postgres and Redis services.

Step 3: Examine the README for additional insights
- Emphasizes client-side privacy (no server video storage), uses ffmpeg.wasm.
- Requires Bun, Docker Compose (Postgres, Redis), environment variables for DATABASE_URL, BETTER_AUTH_SECRET & URL, UPSTASH_REDIS.
- CI pipelines build and deploy to Vercel/Netlify; analytics via external Databuddy.

a. Main components
- Client Browser (React UI + ffmpeg.wasm)
- Next.js Web Server (apps/web)
- Auth Module (packages/auth)
- Database Service (Postgres via packages/db)
- Cache/Rate-Limit Store (Redis/Upstash)
- External Analytics Service (Databuddy)
- CI/CD Pipeline & Hosting (GitHub Actions → Vercel/Netlify)
b. Relationships & interactions
- Browser ↔ Next.js: page requests, static asset fetches, API calls
- Next.js API ↔ Auth Module: internal function calls for login/signup
- Next.js API ↔ Postgres: ORM queries (Drizzle) for user/projects data
- Next.js API ↔ Redis: rate-limiting, ephemeral state
- Browser ↔ ffmpeg.wasm: client-side video processing
- CI/CD → GitHub → Build & Deploy → Hosting
c. Architectural patterns & principles
- Monorepo with horizontally separated concerns (frontend, auth, db)
- App Router (Next.js) with Route Handlers for server-side logic
- Client-heavy processing, server-as-API pattern
- Type-safe ORM (Drizzle) and micro-packages for reusability
- State management via Zustand and custom hooks
d. Key technologies & frameworks
- Next.js 13+, React, TypeScript
- Zustand (state)
- Drizzle ORM (packages/db)
- ffmpeg.wasm (public/ffmpeg)
- Bun (runtime)
- Docker Compose (Postgres, Redis)
- GitHub Actions, Vercel/Netlify

- Layer 1 (Presentation): Browser UI, ffmpeg.wasm
- Layer 2 (Application/API): Next.js server, API route handlers, auth logic
- Layer 3 (Data): Postgres database, Redis cache
- Layer 4 (External): Analytics, CI/CD & Hosting

Step 6: Diagramming guidelines
- Use clear labels: include component name and core tech/version
- Blue rectangles for frontend components
- Purple clouds for external services
- Related elements (e.g., all apps/web submodules inside one container)

Step 7: Emphasize essential architectural elements
- Package and service as its own component
- How data moves end-to-end (user interaction → API → DB → back)
- Be detailed but avoid unnecessary low-level code artifacts; focus on service boundaries and integration points

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        Browser["Client Browser UI (React + TypeScript)"]:::frontend
        FFmpeg["Client-side Video Processing (ffmpeg.wasm)"]:::frontend
    end

    %% Application/API Layer
    subgraph "Application/API Layer"
        subgraph "apps/web"
            NextJS["Next.js Web Server & API Routes"]:::backend
            Zustand["State Management (Zustand stores)"]:::frontend
            DrizzleWeb["Drizzle ORM Config"]:::backend
            RateLimit["Rate-Limiting / Cache Integration"]:::backend
        end
        subgraph "packages/auth"
            Auth["Authentication Module"]:::backend
        end
        subgraph "packages/db"
            DrizzlePkg["Drizzle ORM Config"]:::backend
            DBSchema["DB Schema & Migrations"]:::database
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        Postgres["Postgres Database"]:::database
        Redis["Redis Cache"]:::database
    end

    %% External Services
    subgraph "External Services"
        Analytics["External Analytics (Databuddy)"]:::external
    end

    %% Infrastructure & CI/CD
    subgraph "Infrastructure & CI/CD"
        DockerCompose["Docker Compose Services\n(Postgres & Redis)"]:::external
        CI["CI Pipeline (GitHub Actions with Bun)"]:::external
        Hosting["Hosting (Vercel/Netlify)"]:::external
    end

    %% Relationships
    Browser -->|"fetches pages / API calls"| NextJS
    Browser -->|"processes video"| FFmpeg
    NextJS -->|"auth calls"| Auth
    NextJS -->|"ORM queries"| DBSchema
    NextJS -->|"cache requests"| RateLimit
    NextJS -->|"analytics events"| Analytics
    NextJS -->|"uses config"| DrizzleWeb
    Auth -->|"uses ORM config"| DrizzlePkg
    DBSchema -->|"configured by"| DrizzlePkg
    DBSchema -->|reads/writes| Postgres
    RateLimit -->|reads/writes| Redis
    CI -->|deploys| Hosting
    DockerCompose -->|provides| Postgres
    DockerCompose -->|provides| Redis

    %% Click Events
    click Browser "https://github.com/phangb/opencut/tree/main/apps/web/src"
    click FFmpeg "https://github.com/phangb/opencut/blob/main/apps/web/public/ffmpeg/ffmpeg-core.wasm"
    click NextJS "https://github.com/phangb/opencut/tree/main/apps/web/src/app/api"
    click Zustand "https://github.com/phangb/opencut/tree/main/apps/web/src/stores"
    click DrizzleWeb "https://github.com/phangb/opencut/blob/main/apps/web/drizzle.config.ts"
    click RateLimit "https://github.com/phangb/opencut/blob/main/apps/web/src/lib/rate-limit.ts"
    click Auth "https://github.com/phangb/opencut/tree/main/packages/auth/src"
    click DrizzlePkg "https://github.com/phangb/opencut/blob/main/packages/db/drizzle.config.ts"
    click DBSchema "https://github.com/phangb/opencut/tree/main/packages/db/src"
    click DBSchema "https://github.com/phangb/opencut/tree/main/packages/db/migrations"
    click DockerCompose "https://github.com/phangb/opencut/blob/main/docker-compose.yaml"
    click CI "https://github.com/phangb/opencut/blob/main/.github/workflows/bun-ci.yml"
    click Hosting "https://github.com/phangb/opencut/blob/main/netlify.toml"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#333,stroke-width:1px
    classDef database fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#D8BFD8,stroke:#333,stroke-width:1px
```
