# omni-media/omniclip architecture

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

- Interactive diagram: https://gitdiagram.com/omni-media/omniclip
- Repository: https://github.com/omni-media/omniclip

## Overview

##### Project type and purpose
- Omniclip is an in-browser, open-source video editing web application/library delivered as a set of Web Components.
- It has no central server-side component: all processing (editing, rendering, encoding) happens in the browser using modern APIs (WebCodecs, WebAssembly, Web Workers, OPFS, WebRTC for collaboration).

##### File structure
- Top-level “s/” directory holds all TypeScript source, split into:
- components/ (custom elements for UI panels: landing page, timeline, media, filters, transitions, text, etc.)
- views/ (lower-level view logic and styling for each UI domain)
- context/ (state management: actions, controllers for collaboration, compositor, media, project, timeline, video-export, shortcuts, store)
- tools/ and utils/ (helper libraries: mp4 parsing, hash router, JSON storage proxy, dashify, etc.)
- Configuration files: tsconfig.json, package.json, GitHub workflows (CI/CD).

##### README insights
- Unidirectional data flow: Actions → State → Controllers → Components/Views.
- Tech stack: TypeScript, WebCodecs, WebAssembly (MediaInfoModule.wasm), WebRTC, FFmpegHelper (in WASM or Workers), mp4box.js, @benev/slate for rich text.
- No back-end: all storage uses browser storage (OPFS, IndexedDB via FileSystemHelper) and collaboration via WebRTC peers.

##### Main components
a. UI Layer (blue):
- Web Components (s/components/*)
- View modules (s/views/*)
- User interactions (mouse/keyboard events)
b. State & Action Layer (green):
- Actions dispatcher (s/context/actions.ts)
- Central store (s/context/store/store.ts and state.ts)
c. Controller Layer (orange):
- Collaboration Controller (WebRTC signaling, compressors, message-handling, OPFS manager)
- Timeline Controller (drag-and-drop, effect placement, filmstrip)
- Compositor Controller (animation, filters, text, transition managers, video/audio/image managers)
- Media Controller (media loading, WebCodecs decoding)
- Video-Export Controller (FFmpegHelper, encode_worker, decode_worker, BinaryAccumulator, FPSCounter)
- Project Controller
- Shortcuts Controller
d. Services & Workers (purple):
- Web Workers (compositor.worker.ts, export workers)
- WebAssembly module (MediaInfoModule.wasm)
- mp4box.js adapter
- OPFS (FileSystemHelper) and IndexedDB
e. External Interfaces (grey):
- Browser APIs: WebCodecs, Canvas or WebGL, File System Access API, WebRTC
- 3rd-party libs: mp4box.js, @benev/slate

##### Relationships and data flow
- UI Component emits Action → Action Dispatcher → Updates Store → Notifies Controllers
- Controllers perform side effects:
- Compositor reads state, runs in Worker, renders frames via Canvas/WebCodecs → back to UI for preview
- Video-Export reads timeline/effects state → uses decode_worker & encode_worker → accumulates binary → writes file via OPFS
- Collaboration listens to state changes → serializes diffs → sends via WebRTC DataChannel → remote peers update their store
- State updates propagate back to UI Components → DOM re-render

##### Architectural patterns & design principles
- Unidirectional data flow (Flux-like)
- Layered separation: UI / State / Controllers / Workers / External
- Component-based UI via Web Components (custom elements)
- Encapsulation of side-effects in Controllers and Workers
- Use of browser-native high-performance APIs (WebCodecs, WASM)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer" 
        direction TB
        UIComponents["Web Components\n(s/components)"]:::ui
        UIViewModules["View Modules\n(s/views)"]:::ui
        UserInteraction["User Interaction\n(Mouse/Keyboard)"]:::ui
    end

    %% State & Action Layer
    subgraph "State & Action Layer"
        direction TB
        Actions["Actions Dispatcher\n(s/context/actions.ts)"]:::state
        Store["Central Store\n(s/context/controllers/store/store.ts)"]:::state
        AppState["Application State\n(s/context/state.ts)"]:::state
    end

    %% Controller Layer
    subgraph "Controller Layer"
        direction TB
        CollaborationCtrl["Collaboration Controller\n(s/context/controllers/collaboration/controller.ts)"]:::ctrl
        TimelineCtrl["Timeline Controller\n(s/context/controllers/timeline/controller.ts)"]:::ctrl
        CompositorCtrl["Compositor Controller\n(s/context/controllers/compositor/controller.ts)"]:::ctrl
        MediaCtrl["Media Controller\n(s/context/controllers/media/controller.ts)"]:::ctrl
        VideoExportCtrl["Video-Export Controller\n(s/context/controllers/video-export/controller.ts)"]:::ctrl
        ProjectCtrl["Project Controller\n(s/context/controllers/project/controller.ts)"]:::ctrl
        ShortcutsCtrl["Shortcuts Controller\n(s/context/controllers/shortcuts/controller.ts)"]:::ctrl
    end

    %% Collaboration sub-parts
    subgraph "Collaboration Controller Parts"
        direction TB
        CollCompressor["Compressor Part"]:::ctrl
        CollFileHandler["File Handler Part"]:::ctrl
        CollMsgHandler["Message Handler Part"]:::ctrl
        CollOPFS["OPFS Manager Part"]:::ctrl
    end

    %% Timeline sub-parts
    subgraph "Timeline Parts"
        direction TB
        TimelineDrag["Drag-Related Parts"]:::ctrl
    end

    %% Video-Export sub-parts
    subgraph "Video-Export Workers"
        direction TB
        DecodeWorker["Decode Worker"]:::worker
        EncodeWorker["Encode Worker"]:::worker
    end

    %% Services & Workers Layer
    subgraph "Services & Workers"
        direction TB
        WASM["MediaInfoModule.wasm"]:::worker
        MP4Box["MP4Box Adapter"]:::worker
        FileSysHelper["FileSystem Helper"]:::worker
        JSONProxy["JSON Storage Proxy"]:::worker
        HashRouter["Hash Router"]:::worker
    end

    %% External Interfaces
    subgraph "External Interfaces"
        direction TB
        WebCodecs["WebCodecs API"]:::external
        CanvasAPI["Canvas/WebGL API"]:::external
        FSAPI["File System Access API"]:::external
        WebRTCAPI["WebRTC API"]:::external
        MP4BoxLib["mp4box.js"]:::external
        SlateLib["@benev/slate"]:::external
    end

    %% Relationships
    UserInteraction -->|"emits Action"| Actions
    UIComponents -->|"emits Action"| Actions
    UIViewModules -->|"emits Action"| Actions

    Actions -->|"dispatch"| Store
    Store -->|"state update"| AppState
    AppState -->|"notify"| CollaborationCtrl
    AppState -->|"notify"| TimelineCtrl
    AppState -->|"notify"| CompositorCtrl
    AppState -->|"notify"| MediaCtrl
    AppState -->|"notify"| VideoExportCtrl
    AppState -->|"notify"| ProjectCtrl
    AppState -->|"notify"| ShortcutsCtrl

    CollaborationCtrl --> CollCompressor
    CollaborationCtrl --> CollFileHandler
    CollaborationCtrl --> CollMsgHandler
    CollaborationCtrl --> CollOPFS

    TimelineCtrl --> TimelineDrag

    VideoExportCtrl --> DecodeWorker
    VideoExportCtrl --> EncodeWorker

    CompositorCtrl -->|"spawns"| WASM
    CompositorCtrl -->|"uses Worker"| CompositorWorker[("Compositor Worker")]:::worker

    DecodeWorker -->|"decode frames"| FileSysHelper
    EncodeWorker -->|"encode frames"| FileSysHelper

    CompositorWorker -->|"render"| CanvasAPI
    VideoExportCtrl -->|"write file"| FSAPI
    CollOPFS --> FSAPI

    CollMsgHandler --> WebRTCAPI
    CollCompressor --> MP4BoxLib
    MP4Box --> MP4BoxLib

    MediaCtrl --> WebCodecsAPI["WebCodecs API"]:::external
    MediaCtrl --> MP4Box

    FileSysHelper -->|"store data"| FSAPI

    %% UI re-render
    Store -->|"update"| UIComponents
    Store -->|"update"| UIViewModules

    %% Click Events
    click UIComponents "https://github.com/omni-media/omniclip/tree/main/s/components"
    click UIViewModules "https://github.com/omni-media/omniclip/tree/main/s/views"
    click Actions "https://github.com/omni-media/omniclip/blob/main/s/context/actions.ts"
    click Store "https://github.com/omni-media/omniclip/blob/main/s/context/controllers/store/store.ts"
    click AppState "https://github.com/omni-media/omniclip/blob/main/s/context/state.ts"
    click CollaborationCtrl "https://github.com/omni-media/omniclip/blob/main/s/context/controllers/collaboration/controller.ts"
    click CollCompressor "https://github.com/omni-media/omniclip/blob/main/s/context/controllers/collaboration/parts/compressor.ts"
    click CollFileHandler "https://github.com/omni-media/omniclip/blob/main/s/context/controllers/collaboration/parts/file-handler.ts"
    click CollMsgHandler "https://github.com/omni-media/omniclip/blob/main/s/context/controllers/collaboration/parts/message-handler.ts"
    click CollOPFS "https://github.com/omni-media/omniclip/blob/main/s/context/controllers/collaboration/parts/opfs-manager.ts"
    click TimelineCtrl "https://github.com/omni-media/omniclip/blob/main/s/context/controllers/timeline/controller.ts"
    click TimelineDrag "https://github.com/omni-media/omniclip/tree/main/s/context/controllers/timeline/parts/drag-related"
    click CompositorCtrl "https://github.com/omni-media/omniclip/blob/main/s/context/controllers/compositor/controller.ts"
    click CompositorWorker "https://github.com/omni-media/omniclip/blob/main/s/context/controllers/compositor/worker.ts"
    click MediaCtrl "https://github.com/omni-media/omniclip/blob/main/s/context/controllers/media/controller.ts"
    click VideoExportCtrl "https://github.com/omni-media/omniclip/blob/main/s/context/controllers/video-export/controller.ts"
    click DecodeWorker "https://github.com/omni-media/omniclip/blob/main/s/context/controllers/video-export/parts/decode_worker.ts"
    click EncodeWorker "https://github.com/omni-media/omniclip/blob/main/s/context/controllers/video-export/parts/encode_worker.ts"
    click ProjectCtrl "https://github.com/omni-media/omniclip/blob/main/s/context/controllers/project/controller.ts"
    click ShortcutsCtrl "https://github.com/omni-media/omniclip/blob/main/s/context/controllers/shortcuts/controller.ts"
    click WASM "https://github.com/omni-media/omniclip/blob/main/assets/MediaInfoModule.wasm"
    click MP4Box "https://github.com/omni-media/omniclip/blob/main/s/tools/mp4boxjs/mp4box.adapter.ts"
    click FileSysHelper "https://github.com/omni-media/omniclip/blob/main/s/context/controllers/video-export/helpers/FileSystemHelper/helper.ts"
    click JSONProxy "https://github.com/omni-media/omniclip/blob/main/s/tools/json_storage_proxy.ts"
    click HashRouter "https://github.com/omni-media/omniclip/blob/main/s/tools/hash-router.ts"

    %% Styles
    classDef ui fill:#bbdefb,stroke:#1e88e5,color:#0d47a1;
    classDef state fill:#c8e6c9,stroke:#43a047,color:#1b5e20;
    classDef ctrl fill:#ffe0b2,stroke:#fb8c00,color:#e65100;
    classDef worker fill:#e1bee7,stroke:#8e24aa,color:#4a148c;
    classDef external fill:#cfd8dc,stroke:#607d8b,color:#263238;
```
