# augani/openreel-video architecture

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

- Interactive diagram: https://gitdiagram.com/augani/openreel-video
- Repository: https://github.com/augani/openreel-video

## Overview

1. **Repo shape**
   This is a pnpm monorepo with three main product surfaces:
   - `apps/web`: the primary browser-based video editor
   - `apps/image`: a separate browser-based image editor
   - shared libraries under `packages/*`, especially `packages/core`, `packages/image-core`, and `packages/ui`

2. **Primary architectural split**
   The video editor is intentionally split into a **React UI layer** and a **core engine layer**. UI code lives in `apps/web/src/components`, `stores`, `services`, and `bridges`; media processing and timeline logic live in `packages/core`. The UI orchestrates user interaction, while the core package performs heavy editing, rendering, and export work.

3. **Web editor UI composition**
   `apps/web/src/components/editor` contains the major workspace regions: timeline, preview, inspector, toolbar, dialogs, recorder, templates, and AI panels. These components are mostly presentational and interaction-heavy, but they do not implement media algorithms themselves. They read/write shared app state and call into service/bridge modules.

4. **State management boundary**
   `apps/web/src/stores` uses Zustand stores to hold editor state such as project, timeline, UI, recorder, settings, theme, notifications, and TTS. This store layer is the main coordination point between UI events and engine actions. The editor is built around a stateful but local-only model; there is no central backend database in the normal editing path.

5. **Bridge and service layer**
   `apps/web/src/bridges` is the integration boundary between UI state and core engines. These bridges connect features like audio, effects, graphics, motion tracking, playback, rendering, transitions, photo editing, silence cutting, and text. `apps/web/src/services` handles app-level concerns such as auto-save, project management, secure storage, screen recording, template cloud access, background generation, and processing orchestration.

6. **Core media engine**
   `packages/core` is the main computation layer for the video product. It is organized by domain:
   - `video`: decoding, compositing, WebGPU rendering, transitions, keyframes, frame caching, stabilization, upscaling, effects
   - `audio`: mixing, effects, beat detection, waveform generation, noise reduction, real-time graph processing
   - `text`: subtitles, title rendering, audio-text sync, speech-to-text, animations
   - `graphics` and `effects`: shapes, stickers, particles, SVG, blend modes
   - `photo`: adjustment and retouching
   - `export`: final render/export pipeline
   - `storage`: project serialization and schema handling

7. **Rendering and playback flow**
   The primary runtime flow is: user edits in React UI → stores update → bridges invoke core engines → preview renders through WebGPU/WebCodecs/Web Audio where available. `packages/core/src/video` and `packages/core/src/playback` are the main realtime path, with fallback renderers and frame caches supporting progressive enhancement when hardware features are missing or limited.

8. **Export and background processing**
   Export is handled in `packages/core/src/export` and is coordinated by the web app’s `processing-manager`/export dialog flow. The system is designed for long-running operations with progress reporting and cancellation. Worker-style processing appears throughout the core package, including decode/export helpers and audio worklet-style processing.

9. **Persistence and recovery**
   Projects are stored client-side, not on a primary server path. The app uses IndexedDB-oriented storage and local recovery helpers (`auto-save`, `project-manager`, `secure-storage`, `media-storage`, recovery hooks). Project schema/migration logic exists in both the web app and core/storage layers, showing that durable local project compatibility is a first-class concern.

10. **External services and network boundaries**
   Most editing happens locally, but a few features cross the network boundary:
   - `apps/web/functions/api/proxy` is a Cloudflare Worker-style proxy for API calls
   - `apps/web/src/services/kieai` and related UI support remote AI image generation
   - transcription/TTS-related UI and services integrate with external voice APIs
   - `infra/transcribe-gpu` is a separate Python/Docker deployment for GPU/CPU transcription support
   These are feature-specific integrations rather than the main data path.

11. **Shared UI and design system**
   `packages/ui` provides reusable React primitives and styling utilities used by both apps. This is a presentation-only package that supports consistent controls like dialogs, sliders, toggles, menus, buttons, and color pickers. It reduces duplication but does not own business logic.

12. **Image editor as a parallel product**
   `apps/image` is not a subset of the video editor; it is its own browser-based editor with its own stores, services, tools, filters, and inspector UI. It depends on `packages/image-core` for project/command/operation/schema logic and uses a separate set of adjustment and tool subsystems. Architecturally, it mirrors the same pattern: React UI on top, a domain core package underneath.

13. **Platform and delivery**
   The repo is optimized for the browser with Vite, React, TypeScript, Tailwind, service workers, and PWA assets. GitHub Actions handle CI and review automation. Native wrapper projects for Android and iOS exist in the tree, but the README and code layout indicate the browser app is the primary product surface.

14. **Important diagram boundary**
   If drawing the architecture, the clearest top-level boundary is:
   **UI apps (`apps/web`, `apps/image`) → app state/services → core engine packages (`packages/core`, `packages/image-core`) → browser/platform APIs and optional external services**.
   That boundary captures where user interaction ends and media computation begins, which is the central architectural idea in this repository.

Main entry points: [`apps/web/src/components/editor`](https://github.com/augani/openreel-video/tree/main/apps/web/src/components/editor) (React UI), [`apps/web/src/bridges`](https://github.com/augani/openreel-video/tree/main/apps/web/src/bridges) (Bridges), [`apps/web/src/services`](https://github.com/augani/openreel-video/tree/main/apps/web/src/services) (App services), [`apps/image/src/components/editor`](https://github.com/augani/openreel-video/tree/main/apps/image/src/components/editor) (Image UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_apps_web["Web editor"]
  node_node_web_ui["React UI<br/>app shell"]
  node_node_web_stores[("Editor state<br/>zustand stores")]
  node_node_web_services["App services<br/>orchestration"]
  node_node_web_bridges["Bridges<br/>engine adapters"]
  node_node_web_preview["Preview path<br/>render UI"]
  node_node_web_timeline["Timeline UI<br/>editor workspace"]
  node_node_web_inspector["Inspector UI<br/>editor panels"]
  node_node_web_kieai["KieAI UI<br/>remote AI UI"]
end

subgraph group_group_apps_image["Image editor"]
  node_node_image_ui["Image UI<br/>app shell"]
  node_node_image_stores[("Image state<br/>zustand stores")]
  node_node_image_tools["Image tools<br/>editing tools"]
  node_node_image_services["Image services<br/>orchestration"]
end

subgraph group_group_packages_core["Video core"]
  node_node_core_video["Video engine<br/>realtime media core"]
  node_node_core_audio["Audio engine<br/>media core"]
  node_node_core_text["Text engine<br/>media core"]
  node_node_core_export["Export pipeline<br/>long-running render"]
  node_node_core_storage[("Project storage<br/>schema/persistence")]
end

subgraph group_group_packages_shared["Shared packages"]
  node_node_shared_ui["UI kit<br/>react primitives"]
  node_node_image_core["Image core<br/>domain core"]
end

subgraph group_group_platform["Platform"]
  node_node_platform_api(("Platform APIs<br/>browser/runtime"))
  node_node_platform_external(("External services<br/>network boundaries"))
end

node_node_web_ui -->|"reads/writes"| node_node_web_stores
node_node_web_stores -->|"drives"| node_node_web_bridges
node_node_web_ui -->|"renders"| node_node_web_preview
node_node_web_ui -->|"uses"| node_node_web_timeline
node_node_web_ui -->|"uses"| node_node_web_inspector
node_node_web_ui -->|"opens"| node_node_web_kieai
node_node_web_services -->|"syncs"| node_node_web_stores
node_node_web_services -->|"calls"| node_node_platform_external
node_node_web_bridges -->|"invokes"| node_node_core_video
node_node_web_bridges -->|"invokes"| node_node_core_audio
node_node_web_bridges -->|"invokes"| node_node_core_text
node_node_web_bridges -->|"serializes"| node_node_core_storage
node_node_web_services -->|"coordinates"| node_node_core_export
node_node_image_ui -->|"reads/writes"| node_node_image_stores
node_node_image_ui -->|"uses"| node_node_image_tools
node_node_image_services -->|"orchestrates"| node_node_image_core
node_node_image_ui -->|"uses"| node_node_image_services
node_node_core_video -->|"runs on"| node_node_platform_api
node_node_core_audio -->|"runs on"| node_node_platform_api
node_node_core_export -->|"runs on"| node_node_platform_api
node_node_core_storage -->|"persists on"| node_node_platform_api
node_node_shared_ui -->|"supports"| node_node_web_ui
node_node_shared_ui -->|"supports"| node_node_image_ui
node_node_image_core -->|"persists on"| node_node_platform_api
node_node_platform_external -->|"integrates with"| node_node_web_services

click node_node_web_ui "https://github.com/augani/openreel-video/tree/main/apps/web/src/components/editor"
click node_node_web_stores "https://github.com/augani/openreel-video/tree/main/apps/web/src/stores"
click node_node_web_services "https://github.com/augani/openreel-video/tree/main/apps/web/src/services"
click node_node_web_bridges "https://github.com/augani/openreel-video/tree/main/apps/web/src/bridges"
click node_node_web_preview "https://github.com/augani/openreel-video/tree/main/apps/web/src/components/editor/preview"
click node_node_web_timeline "https://github.com/augani/openreel-video/tree/main/apps/web/src/components/editor/timeline"
click node_node_web_inspector "https://github.com/augani/openreel-video/tree/main/apps/web/src/components/editor/inspector"
click node_node_web_kieai "https://github.com/augani/openreel-video/tree/main/apps/web/src/components/editor/kieai"
click node_node_image_ui "https://github.com/augani/openreel-video/tree/main/apps/image/src/components/editor"
click node_node_image_stores "https://github.com/augani/openreel-video/tree/main/apps/image/src/stores"
click node_node_image_tools "https://github.com/augani/openreel-video/tree/main/apps/image/src/tools"
click node_node_image_services "https://github.com/augani/openreel-video/tree/main/apps/image/src/services"
click node_node_core_video "https://github.com/augani/openreel-video/tree/main/packages/core/src/video"
click node_node_core_audio "https://github.com/augani/openreel-video/tree/main/packages/core/src/audio"
click node_node_core_text "https://github.com/augani/openreel-video/tree/main/packages/core/src/text"
click node_node_core_export "https://github.com/augani/openreel-video/tree/main/packages/core/src/export"
click node_node_core_storage "https://github.com/augani/openreel-video/tree/main/packages/core/src/storage"
click node_node_shared_ui "https://github.com/augani/openreel-video/tree/main/packages/ui/src/components"
click node_node_image_core "https://github.com/augani/openreel-video/tree/main/packages/image-core/src"
click node_node_platform_external "https://github.com/augani/openreel-video/tree/main/apps/web/functions/api/proxy"

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_node_web_ui,node_node_web_stores,node_node_web_services,node_node_web_bridges,node_node_web_preview,node_node_web_timeline,node_node_web_inspector,node_node_web_kieai toneBlue
class node_node_image_ui,node_node_image_stores,node_node_image_tools,node_node_image_services toneAmber
class node_node_core_video,node_node_core_audio,node_node_core_text,node_node_core_export,node_node_core_storage toneMint
class node_node_shared_ui,node_node_image_core toneRose
class node_node_platform_api,node_node_platform_external toneIndigo
```

## Components

### Web editor

Primary browser-based video editor surface and its local app layers.

- [React UI](https://github.com/augani/openreel-video/tree/main/apps/web/src/components/editor): app shell · Main video editor interface: workspace regions, dialogs, preview, timeline, inspector, and tooling UI. · `apps/web/src/components/editor`
- [Editor state](https://github.com/augani/openreel-video/tree/main/apps/web/src/stores): zustand stores · Local state coordination for project, timeline, UI, recorder, settings, notifications, theme, and TTS. · `apps/web/src/stores`
- [App services](https://github.com/augani/openreel-video/tree/main/apps/web/src/services): orchestration · Autosave, project management, secure storage, processing, templates, recording, and cloud/AI integrations. · `apps/web/src/services`
- [Bridges](https://github.com/augani/openreel-video/tree/main/apps/web/src/bridges): engine adapters · Feature-specific adapters that connect UI state and app events to core media engines. · `apps/web/src/bridges`
- [Preview path](https://github.com/augani/openreel-video/tree/main/apps/web/src/components/editor/preview): render UI · Browser preview and canvas/three.js rendering used for realtime playback feedback. · `apps/web/src/components/editor/preview`
- [Timeline UI](https://github.com/augani/openreel-video/tree/main/apps/web/src/components/editor/timeline): editor workspace · Clip lanes, playhead, markers, keyframes, and timeline interactions. · `apps/web/src/components/editor/timeline`
- [Inspector UI](https://github.com/augani/openreel-video/tree/main/apps/web/src/components/editor/inspector): editor panels · Clip and project panels for audio, text, motion, effects, AI, and other edit controls. · `apps/web/src/components/editor/inspector`
- [KieAI UI](https://github.com/augani/openreel-video/tree/main/apps/web/src/components/editor/kieai): remote AI UI · Browser dialogs and forms for remote image generation workflows. · `apps/web/src/components/editor/kieai`

### Image editor

Standalone browser-based image editor surface.

- [Image UI](https://github.com/augani/openreel-video/tree/main/apps/image/src/components/editor): app shell · Standalone image editor interface with canvas, layers, panels, inspector, and tool controls. · `apps/image/src/components/editor`
- [Image state](https://github.com/augani/openreel-video/tree/main/apps/image/src/stores): zustand stores · Local image editor state for canvas, selection, history, color, project, and UI. · `apps/image/src/stores`
- [Image tools](https://github.com/augani/openreel-video/tree/main/apps/image/src/tools): editing tools · Brush, retouch, transform, vector, and text tools used by the image editor. · `apps/image/src/tools`
- [Image services](https://github.com/augani/openreel-video/tree/main/apps/image/src/services): orchestration · Export, background removal, template, font, keyboard, and project migration services. · `apps/image/src/services`

### Video core

Computation-heavy video editing, playback, export, and media subsystems.

- [Video engine](https://github.com/augani/openreel-video/tree/main/packages/core/src/video): realtime media core · Main video computation path for decode, compose, render, playback, caching, transitions, keyframes, stabilization, and effects. · `packages/core/src/video`
- [Audio engine](https://github.com/augani/openreel-video/tree/main/packages/core/src/audio): media core · Mixing, beat detection, waveform generation, noise reduction, realtime graph processing, and audio effects. · `packages/core/src/audio`
- [Text engine](https://github.com/augani/openreel-video/tree/main/packages/core/src/text): media core · Subtitles, title rendering, speech-to-text, audio-text sync, and text animations. · `packages/core/src/text`
- [Export pipeline](https://github.com/augani/openreel-video/tree/main/packages/core/src/export): long-running render · Final render/export execution, including worker-based processing and progress/cancellation handling. · `packages/core/src/export`
- [Project storage](https://github.com/augani/openreel-video/tree/main/packages/core/src/storage): schema/persistence · Client-side project serialization, schema handling, cache management, and storage engine logic. · `packages/core/src/storage`

### Shared packages

Reusable UI and image-domain libraries shared across app surfaces.

- [UI kit](https://github.com/augani/openreel-video/tree/main/packages/ui/src/components): react primitives · Reusable presentation components and styling utilities shared by both apps. · `packages/ui/src/components`
- [Image core](https://github.com/augani/openreel-video/tree/main/packages/image-core/src): domain core · Command, operation, schema, migration, project, mask, selection, and adjustment model for the image editor. · `packages/image-core/src`

### Platform

Browser, worker, cloud, and delivery boundaries around the product.

- **Platform APIs**: browser/runtime · IndexedDB, workers, WebGPU/WebCodecs/Web Audio, service workers, and browser delivery surfaces.
- [External services](https://github.com/augani/openreel-video/tree/main/apps/web/functions/api/proxy): network boundaries · Cloud proxy, AI generation, voice/transcription integrations, and GPU transcription deployment. · `apps/web/functions/api/proxy`

## Connections

- React UI → Editor state: reads/writes · UI interactions update local editor state and react to state changes.
- Editor state → Bridges: drives · State changes trigger engine-adapter calls for editing actions and playback.
- React UI → Preview path: renders · Workspace preview surfaces show realtime composition feedback.
- React UI → Timeline UI: uses · Timeline components provide the main clip-editing interaction surface.
- React UI → Inspector UI: uses · Inspector panels expose per-clip and per-project controls.
- React UI → KieAI UI: opens · AI image generation flows are exposed through dedicated dialogs and forms.
- App services → Editor state: syncs · Autosave, recovery, and processing services coordinate with local state.
- App services → External services: calls · Remote AI, voice, and proxy-backed integrations cross the network boundary.
- Bridges → Video engine: invokes · Video editing actions are delegated to the core engine layer.
- Bridges → Audio engine: invokes · Audio-related edit actions route into the audio engine.
- Bridges → Text engine: invokes · Text, subtitles, TTS, and sync features route into the text engine.
- Bridges → Project storage: serializes · Bridges participate in project and timeline persistence flows.
- App services → Export pipeline: coordinates · Export dialogs and processing manager coordinate long-running renders.
- Image UI → Image state: reads/writes · Image editor interactions are coordinated through local stores.
- Image UI → Image tools: uses · Canvas and inspector UI expose image editing tools.
- Image services → Image core: orchestrates · Services manage export, migrations, and project-level operations on top of the image core.
- Image UI → Image services: uses · Dialogs and panels call into image editor services.
- Video engine → Platform APIs: runs on · Realtime rendering and decoding depend on browser graphics and media APIs where available.
- Audio engine → Platform APIs: runs on · Audio processing uses browser audio and worker-style execution paths.
- Export pipeline → Platform APIs: runs on · Export workers and browser runtime support the render pipeline.
- Project storage → Platform APIs: persists on · Project durability relies on client-side storage and recovery APIs.
- UI kit → React UI: supports · Shared presentation primitives reduce UI duplication in the web editor.
- UI kit → Image UI: supports · Shared controls and styling are reused by the image editor.
- Image core → Platform APIs: persists on · Image project schema and operations ultimately run in the browser runtime.
- External services → App services: integrates with · Networked feature integrations are consumed by app-level services.
