How phangb/opencut works
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