# eatdesignlove/react-video-timestone architecture

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

- Interactive diagram: https://gitdiagram.com/eatdesignlove/react-video-timestone
- Repository: https://github.com/eatdesignlove/react-video-timestone

## Overview

##### Project type and purpose
- This is a React component library (“react-video-timestone”) that provides a multi‐video timeline component with built-in preloading, marker system, reverse/forward control, and blob caching.
- It includes a demo application (in src/) built with Vite to showcase the library.

##### File structure
- Top-level directories:
- lib/ – compiled distribution code organized into submodules: model, ui, types, utils
- src/ – demo application source (React + CSS-in-JS)
- public/ – static assets (video files for the demo)
- Config and build files:
- package.json, tsconfig*.json, vite.config.ts, eslint.config.js
- .changeset/ and CHANGELOG.md for release management

##### Key insights from README
- Core architecture revolves around:
- VideoTimestone component (entry point in lib/index.ts)
- Internal state management (context + reducer) under lib/model
- UI subcomponents under lib/ui (video, controls, timeline markers)
- Utility routines for preloading and blob conversion in lib/utils
- Runtime flow: load URLs → preload into blobs → dispatch state events → render video(s) + controls → handle markers and callbacks.

##### Main components
a. Library Source
– Model module: preload-videos, state context, reducer, hooks
– UI module: Video, controls (play/pause/seek), timeline markers
– Utils module: blob conversion, marker setup
– Types module: shared TypeScript interfaces/constants
b. Build & Packaging
– TypeScript compiler & bundler (Vite during demo, Rollup/TS for npm build)
– Output: ES modules / CommonJS under lib/ → published to npm
c. Demo Application
– Vite host (index.html, main.tsx)
– App components (header, hero, package-guide, footer, etc.) under src/ui
– Static assets loader (public/demo*.mp4)
d. External Consumers
– Any React project importing ‘react-video-timestone’ from npm

##### Relationships and interactions
- Source modules interlink: Model → UI renders based on model’s state/context → Utils support model
- Build pipeline transforms lib source into distributable package
- Demo app imports built library from lib/ (or via npm)
- At runtime, VideoTimestone instantiates HTMLVideoElements, uses blob URLs from Utils, drives UI via Model state
- Application code (demo or third-party) interacts via props, marker callbacks, and ref methods

##### Architectural patterns & design principles
- Modular separation: core logic (model), presentation (ui), utilities
- React Context + Reducer pattern for state management
- Composition: top-level VideoTimestone composes multiple subcomponents
- CSS-in-JS for scoped styling under lib/ui/*.css.ts
- Blob caching for zero-buffer navigation

##### Detail
- Where marker callbacks plug in
- That CSS-in-JS styling is bundled with UI components

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Library Source Modules
    subgraph "Library Source"
        direction TB
        Entry["VideoTimestone<br/>(Entry Point)"]:::source
        Model["Model Module"]:::source
        UI["UI Module"]:::source
        Utils["Utils Module"]:::source
        Types["Types Module"]:::source

        Entry -->|imports| Model
        Entry -->|imports| UI
        Entry -->|imports| Utils
        Entry -->|imports| Types

        %% Model internals
        subgraph "Model Internals"
            direction TB
            Preload["preload-videos"]:::source
            AnimHook["use-video-animation"]:::source
            StateHook["use-video-timestone-state"]:::source
            Context["VideoTimestone Context"]:::source
            Reducer["VideoTimestone Reducer"]:::source

            Model --> Preload
            Model --> AnimHook
            Model --> StateHook
            Model --> Context
            Model --> Reducer
        end

        %% Types internals
        Types --> TimelineTypes["timestone types"]:::source

        %% UI internals
        subgraph "UI Internals"
            direction TB
            VTUI["VideoTimestone UI"]:::source
            VTUI_CSS["video-timestone.css.ts"]:::source
            Control["Video Control UI"]:::source
            Control_CSS["video-control.css.ts"]:::source
            VideoComp["Video Player UI"]:::source
            VideoCSS["video.css.ts"]:::source

            UI --> VTUI
            UI --> VTUI_CSS
            UI --> Control
            UI --> Control_CSS
            UI --> VideoComp
            UI --> VideoCSS
        end

        %% Utils internals
        Utils --> SetupMarkers["setup-markers"]:::source
    end

    %% Build & Publish
    subgraph "Build & Publish"
        direction TB
        TSBundle["TypeScript Compiler & Rollup"]:::build
        ViteBuild["Vite (Demo Build)"]:::build
        NPM["npm Registry"]:::cloud

        TSBundle -->|publishes| NPM
        ViteBuild -->|provides lib for demo| DemoApp
    end

    %% Demo & Consumers
    subgraph "Demo & Consumers"
        direction TB
        DemoApp["Demo Application"]:::demo
        External["External React App"]:::demo
        Assets[(Video Files)]:::asset

        DemoApp -->|imports from| Entry
        DemoApp -->|loads| Assets
        External -->|imports from| Entry
    end

    %% Demo internals
    subgraph "Demo Application Structure"
        direction TB
        HTML["index.html"]:::demo
        MainTS["main.tsx"]:::demo
        RootComp["demo-app.tsx"]:::demo
        DemoUI["src/ui/index.ts"]:::demo

        HTML --> MainTS
        MainTS --> RootComp
        RootComp --> DemoUI

        subgraph "Demo UI Components"
            direction TB
            Header["Header"]:::demo
            Hero["Hero"]:::demo
            Features["Features"]:::demo
            PackageGuide["Package Guide"]:::demo
            DemoFeature["Demo Feature"]:::demo
            Footer["Footer"]:::demo
        end

        DemoUI --> Header
        DemoUI --> Hero
        DemoUI --> Features
        DemoUI --> PackageGuide
        DemoUI --> DemoFeature
        DemoUI --> Footer
    end

    %% Connections
    Preload -->|uses| Assets
    Assets -->|feeds| Preload
    Context -->|provides state to| UI
    Reducer -->|handles actions for| Context

    %% Click Events
    click Entry "https://github.com/eatdesignlove/react-video-timestone/blob/main/lib/index.ts"
    click Model "https://github.com/eatdesignlove/react-video-timestone/blob/main/lib/model/index.ts"
    click Preload "https://github.com/eatdesignlove/react-video-timestone/blob/main/lib/model/preload-videos.ts"
    click AnimHook "https://github.com/eatdesignlove/react-video-timestone/blob/main/lib/model/use-video-animation.ts"
    click StateHook "https://github.com/eatdesignlove/react-video-timestone/blob/main/lib/model/use-video-timestone-state.ts"
    click Context "https://github.com/eatdesignlove/react-video-timestone/blob/main/lib/model/video-timestone-context.ts"
    click Reducer "https://github.com/eatdesignlove/react-video-timestone/blob/main/lib/model/video-timestone-reducer.ts"
    click Types "https://github.com/eatdesignlove/react-video-timestone/blob/main/lib/types/index.ts"
    click TimelineTypes "https://github.com/eatdesignlove/react-video-timestone/blob/main/lib/types/timestone.ts"
    click UI "https://github.com/eatdesignlove/react-video-timestone/blob/main/lib/ui/index.ts"
    click VTUI "https://github.com/eatdesignlove/react-video-timestone/blob/main/lib/ui/video-timestone/index.tsx"
    click VTUI_CSS "https://github.com/eatdesignlove/react-video-timestone/blob/main/lib/ui/video-timestone/video-timestone.css.ts"
    click Control "https://github.com/eatdesignlove/react-video-timestone/blob/main/lib/ui/video-control/index.tsx"
    click Control_CSS "https://github.com/eatdesignlove/react-video-timestone/blob/main/lib/ui/video-control/video-control.css.ts"
    click VideoComp "https://github.com/eatdesignlove/react-video-timestone/blob/main/lib/ui/video/index.tsx"
    click VideoCSS "https://github.com/eatdesignlove/react-video-timestone/blob/main/lib/ui/video/video.css.ts"
    click Utils "https://github.com/eatdesignlove/react-video-timestone/blob/main/lib/utils/index.ts"
    click SetupMarkers "https://github.com/eatdesignlove/react-video-timestone/blob/main/lib/utils/setup-markers.ts"
    click HTML "https://github.com/eatdesignlove/react-video-timestone/blob/main/index.html"
    click MainTS "https://github.com/eatdesignlove/react-video-timestone/blob/main/src/main.tsx"
    click RootComp "https://github.com/eatdesignlove/react-video-timestone/blob/main/src/demo-app.tsx"
    click DemoUI "https://github.com/eatdesignlove/react-video-timestone/blob/main/src/ui/index.ts"
    click Header "https://github.com/eatdesignlove/react-video-timestone/blob/main/src/ui/header/index.tsx"
    click Hero "https://github.com/eatdesignlove/react-video-timestone/blob/main/src/ui/hero/index.tsx"
    click Features "https://github.com/eatdesignlove/react-video-timestone/blob/main/src/ui/features/index.tsx"
    click PackageGuide "https://github.com/eatdesignlove/react-video-timestone/blob/main/src/ui/package-guide/index.tsx"
    click DemoFeature "https://github.com/eatdesignlove/react-video-timestone/blob/main/src/ui/demo/index.tsx"
    click Footer "https://github.com/eatdesignlove/react-video-timestone/blob/main/src/ui/footer/index.tsx"

    %% Styles
    classDef source fill:#e3f2fd,stroke:#90caf9
    classDef build fill:#fff3e0,stroke:#ffb74d
    classDef demo fill:#e8f5e9,stroke:#81c784
    classDef asset fill:#f3e5f5,stroke:#ce93d8
    classDef cloud fill:#e0f7fa,stroke:#4dd0e1
```
