# webav-tech/webav architecture

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

- Interactive diagram: https://gitdiagram.com/webav-tech/webav
- Repository: https://github.com/webav-tech/webav

## Overview

##### Project type and purpose
- This is a monorepo for an open-source WebAV SDK: a collection of npm packages for client-side audio/video processing (av-cliper, av-canvas, av-recorder, internal-utils) plus a documentation/demo site (doc-site).
- Its purpose is to provide high-performance, browser-native video editing/recording capabilities built on WebCodecs, WebAudio, Canvas, and to deliver demos and API docs via a static site.

##### File structure
- Top-level:
- pnpm-workspace.yaml + package.json + tsconfig.json → workspace root & shared TS config
- .github/workflows → CI for testing, building, releasing, doc-site deploy
- scripts → commit verification
- packages/… → four separate modules:
– av-cliper: core audio/video data processing
– av-canvas: interactive canvas UI on top of av-cliper
– av-recorder: media stream recorder
– internal-utils: shared helpers (logging, event, stream utils)
- doc-site/ → Dumi-based documentation and demo site
- Each package has src/, __tests__/, demo/, vite.config.ts, tsconfig.json, package.json.
- CHANGELOG.md, LICENSE, README files at root and per package.

##### Insights from README
- Describes features (cross-platform, zero server cost, high performance) and use-cases (batch processing, live streaming, editing).
- Highlights core APIs in av-cliper (IClip, Sprite, Combinator), av-canvas (AVCanvas), av-recorder (AVRecorder).
- Guides on development workflow (pnpm install, build, run demos, tests).

##### Elements
- Clear labels for each component (module names, doc-site, CI, external services)
- Rectangles for code modules
- Hexagons for CI/CD
- Shadows or grouping for workspace boundaries

##### Final guidance
- Every essential element: repo root, workspace config, individual package layers, docs site, CI pipeline, external integrations, developer and consumer roles.
- Use a modular layout—left side for source modules, right side for consumers and deployment, bottom for CI/CD.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Top-level developer
    Dev[("Developers")]:::user

    %% Monorepo Root
    subgraph "Monorepo Root"
        direction TB
        WC["pnpm-workspace.yaml"]:::config
        PJ["package.json"]:::config
        TS["tsconfig.json"]:::config
        SC["scripts/verify-commit.js"]:::script
    end

    Dev -->|clones & modifies| WC
    Dev --> PJ
    Dev --> TS
    Dev --> SC

    %% Packages Layer
    subgraph "Packages" 
        direction TB
        subgraph "internal-utils" 
            direction TB
            IU1["src/index.ts"]:::utility
            IU2["src/log.ts"]:::utility
            IU3["src/event-tool.ts"]:::utility
            IU4["src/stream-utils.ts"]:::utility
        end
        subgraph "av-cliper"
            direction TB
            AC1["src/index.ts"]:::core
            AC2["src/av-utils.ts"]:::core
            AC3["src/combinator.ts"]:::core
            AC4["src/clips/iclip.ts"]:::core
            AC5["src/sprite/base-sprite.ts"]:::core
        end
        subgraph "av-canvas"
            direction TB
            CAN1["src/index.ts"]:::ui
            CAN2["src/av-canvas.ts"]:::ui
            CAN3["src/sprites/sprite-manager.ts"]:::ui
            CAN4["src/utils.ts"]:::ui
        end
        subgraph "av-recorder"
            direction TB
            REC1["src/av-recorder.ts"]:::recorder
            REC2["src/types.ts"]:::recorder
        end
    end

    %% Dependencies
    IU1 & IU2 & IU3 & IU4 -->|shared dependency| AC1 & CAN1 & REC1
    AC1 -->|base engine| CAN1
    AC1 -->|output streams| REC1

    %% Documentation Site
    subgraph "Doc-site"
        direction TB
        DS1[".dumirc.ts"]:::doc
        DS2["docs/api/index.md"]:::doc
        DS3["docs/demo/*.md/tsx"]:::doc
        DS4["package.json"]:::config
        DS5["tsconfig.json"]:::config
    end

    DS1 & DS2 & DS3 -->|imports built packages| AC1 & CAN1 & REC1

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        direction TB
        CI1[".github/workflows/ci.yml"]:::ci
        CI2[".github/workflows/deploy-doc-site.yml"]:::ci
        CI3[".github/workflows/release.yml"]:::ci
    end

    CI1 -->|runs tests/build| AC1 & CAN1 & REC1 & IU1
    CI3 -->|publishes packages| npm
    CI2 -->|deploys doc-site| GHPages

    %% External Services
    npm[(npm registry)]:::service
    GHPages[(GitHub Pages)]:::service
    Consumers[("Consumers\n(Web Apps)")]:::user

    AC1 & CAN1 & REC1 -->|publish| npm
    DS1 -->|deploy| GHPages
    Consumers <--|install| npm

    Dev --> CI1
    Dev --> CI2
    Dev --> CI3

    %% Click events
    click WC "https://github.com/webav-tech/webav/blob/main/pnpm-workspace.yaml"
    click PJ "https://github.com/webav-tech/webav/blob/main/package.json"
    click TS "https://github.com/webav-tech/webav/blob/main/tsconfig.json"
    click SC "https://github.com/webav-tech/webav/blob/main/scripts/verify-commit.js"

    click CI1 "https://github.com/webav-tech/webav/blob/main/.github/workflows/ci.yml"
    click CI2 "https://github.com/webav-tech/webav/blob/main/.github/workflows/deploy-doc-site.yml"
    click CI3 "https://github.com/webav-tech/webav/blob/main/.github/workflows/release.yml"

    click IU1 "https://github.com/webav-tech/webav/blob/main/packages/internal-utils/src/index.ts"
    click IU2 "https://github.com/webav-tech/webav/blob/main/packages/internal-utils/src/log.ts"
    click IU3 "https://github.com/webav-tech/webav/blob/main/packages/internal-utils/src/event-tool.ts"
    click IU4 "https://github.com/webav-tech/webav/blob/main/packages/internal-utils/src/stream-utils.ts"

    click AC1 "https://github.com/webav-tech/webav/blob/main/packages/av-cliper/src/index.ts"
    click AC2 "https://github.com/webav-tech/webav/blob/main/packages/av-cliper/src/av-utils.ts"
    click AC3 "https://github.com/webav-tech/webav/blob/main/packages/av-cliper/src/combinator.ts"
    click AC4 "https://github.com/webav-tech/webav/blob/main/packages/av-cliper/src/clips/iclip.ts"
    click AC5 "https://github.com/webav-tech/webav/blob/main/packages/av-cliper/src/sprite/base-sprite.ts"

    click CAN1 "https://github.com/webav-tech/webav/blob/main/packages/av-canvas/src/index.ts"
    click CAN2 "https://github.com/webav-tech/webav/blob/main/packages/av-canvas/src/av-canvas.ts"
    click CAN3 "https://github.com/webav-tech/webav/blob/main/packages/av-canvas/src/sprites/sprite-manager.ts"
    click CAN4 "https://github.com/webav-tech/webav/blob/main/packages/av-canvas/src/utils.ts"

    click REC1 "https://github.com/webav-tech/webav/blob/main/packages/av-recorder/src/av-recorder.ts"
    click REC2 "https://github.com/webav-tech/webav/blob/main/packages/av-recorder/src/types.ts"

    click DS1 "https://github.com/webav-tech/webav/blob/main/doc-site/.dumirc.ts"
    click DS2 "https://github.com/webav-tech/webav/blob/main/doc-site/docs/api/index.md"
    click DS3 "https://github.com/webav-tech/webav/blob/main/doc-site/docs/demo/*.md and *.tsx"
    click DS4 "https://github.com/webav-tech/webav/blob/main/doc-site/package.json"
    click DS5 "https://github.com/webav-tech/webav/blob/main/doc-site/tsconfig.json"

    %% Styles
    classDef user fill:#fcc,stroke:#900,color:#000
    classDef config fill:#eef,stroke:#33a,color:#000
    classDef script fill:#fde,stroke:#e85,color:#000
    classDef utility fill:#cfc,stroke:#080,color:#000
    classDef core fill:#bbf,stroke:#00f,color:#000
    classDef ui fill:#bdf,stroke:#06f,color:#000
    classDef recorder fill:#fbf,stroke:#f0f,color:#000
    classDef doc fill:#ffd,stroke:#aa0,color:#000
    classDef ci fill:#f96,stroke:#963,color:#000
    classDef service fill:#ddd,stroke:#666,color:#000
```
