# yoke0104x/vod-hwc-shard-upload architecture

> Architecture diagram of the GitHub repository yoke0104x/vod-hwc-shard-upload, 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/yoke0104x/vod-hwc-shard-upload
- Repository: https://github.com/yoke0104x/vod-hwc-shard-upload

## Overview

##### Project Type and Purpose
- This is an NPM client-side SDK library (“vod-hwc-shard-upload”) whose sole purpose is to provide a convenient wrapper around Huawei Cloud VOD’s REST API for large video uploads (shard/chunk upload).
- It is not a full-stack app or microservice, but a reusable module that any TypeScript/JavaScript project can import.

##### Main Architectural Components
A. Consumer Application
- Your code (or any downstream project) that calls `new HuaweiVodUploader(...)` and `uploader.upload(...)`.
B. SDK Entry Point
- `src/index.ts` exports the `HuaweiVodUploader` class.
C. Core Uploader Module
- `HuaweiVodUploader` (in `src/HuaweiVodUploader.ts`):
1. Configuration & Initialization
– Accepts projectId, region, token, bufferSize, etc.
2. Upload Workflow Orchestrator (Facade)
– Manages lifecycle: start session → shard file → upload shards in loop → finalize.
3. Shard Generator
– Reads file from disk/stream, slices into buffers of `bufferSize`.
4. HTTP Client
– Sends REST calls to Huawei Cloud VOD endpoints:
- CreateUploadSession
- UploadShard (per chunk)
- CompleteUploadSession
5. Progress Emitter
– Calls back `onProgress` with aggregated progress data after each shard.
D. External Dependencies & Services
- Huawei Cloud VOD API (REST).
- Node.js built-ins (`fs`, `stream`, etc.) or browser equivalents.
E. Build & Packaging
- `rollup.config.ts` bundles source into distributable formats (ESM/CJS).
- `tsconfig.json` controls TypeScript compilation.
F. CI/CD
- `.github/workflows/node.js.yml` runs lint/tests/build on each push.

##### Relationships & Data Flows
- Consumer → (calls) → HuaweiVodUploader.upload()
- HuaweiVodUploader → (initializes) → REST “CreateUploadSession”
- HuaweiVodUploader → (reads + chunks file) → Shard Generator
- Shard Generator → (passes buffers) → HTTP Client
- HTTP Client → (POST each shard) → REST “UploadShard” → (receives) → SDK
- After last shard, SDK → (calls) → REST “CompleteUploadSession”
- SDK → (reports) → onProgress / final Promise resolution → Consumer

##### Architectural Patterns & Principles
- Facade Pattern: `HuaweiVodUploader` hides complexity of sharding and all API calls behind a simple interface.
- Single Responsibility: separate chunking logic, HTTP logic, and orchestration.
- Streaming & Buffering: process large files in chunks to avoid memory overload.
- Promise-based async flow with callback hooks for extensibility.

## Diagram (Mermaid)

```mermaid
flowchart TB
    ConsumerApp["Consumer Application"]:::consumer

    subgraph "SDK Library"
        direction TB
        EntryPoint["src/index.ts"]:::sdk
        Config["Config (projectId, region, token, bufferSize)"]:::note
        Facade["HuaweiVodUploader"]:::sdk
        ShardGen["Shard Generator"]:::sdk
        HttpClient["HTTP Client"]:::sdk
    end

    External["Huawei Cloud VOD API"]:::external

    ConsumerApp -->|"new HuaweiVodUploader(...); upload()"| EntryPoint
    EntryPoint -->|exports| Facade
    Facade -->|uses| Config
    Facade -->|"CreateUploadSession"| External
    Facade -->|"start shard loop"| ShardGen
    ShardGen -->|"buffers of bufferSize"| HttpClient
    HttpClient -->|"POST UploadShard #n"| External
    External -->|response| HttpClient
    HttpClient -->|back to facade| Facade
    Facade -->|"CompleteUploadSession"| External
    Facade -.->|"onProgress event"| ConsumerApp
    Facade -->|"Promise resolved"| ConsumerApp

    subgraph "Build & CI/CD"
        Rollup["rollup.config.ts"]:::build
        Tsconfig["tsconfig.json"]:::build
        PackageJson["package.json"]:::build
        NpmIgnore[".npmignore"]:::build
        GitIgnore[".gitignore"]:::build
        Readme["README.md"]:::build
        CI[".github/workflows/node.js.yml"]:::build
    end

    classDef sdk fill:#cce5ff,stroke:#004085,stroke-width:1px
    classDef external fill:#d4edda,stroke:#155724,stroke-width:1px
    classDef consumer fill:#f8d7da,stroke:#721c24,stroke-width:1px
    classDef build fill:#e2e3e5,stroke:#6c757d,stroke-width:1px
    classDef note fill:#fff3cd,stroke:#856404,stroke-width:1px

    click EntryPoint "https://github.com/yoke0104x/vod-hwc-shard-upload/blob/main/src/index.ts"
    click Facade "https://github.com/yoke0104x/vod-hwc-shard-upload/blob/main/src/HuaweiVodUploader.ts"
    click Rollup "https://github.com/yoke0104x/vod-hwc-shard-upload/blob/main/rollup.config.ts"
    click Tsconfig "https://github.com/yoke0104x/vod-hwc-shard-upload/blob/main/tsconfig.json"
    click PackageJson "https://github.com/yoke0104x/vod-hwc-shard-upload/blob/main/package.json"
    click NpmIgnore "https://github.com/yoke0104x/vod-hwc-shard-upload/blob/main/.npmignore"
    click GitIgnore "https://github.com/yoke0104x/vod-hwc-shard-upload/blob/main/.gitignore"
    click Readme "https://github.com/yoke0104x/vod-hwc-shard-upload/blob/main/README.md"
    click CI "https://github.com/yoke0104x/vod-hwc-shard-upload/blob/main/.github/workflows/node.js.yml"
```
