# tencentyun/cos-wx-sdk-v5 architecture

> Architecture diagram of the GitHub repository tencentyun/cos-wx-sdk-v5, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tencentyun/cos-wx-sdk-v5
- Repository: https://github.com/tencentyun/cos-wx-sdk-v5

## Overview

##### Project type and purpose
- This is a JavaScript SDK (“cos-wx-sdk-v5”) for Tencent Cloud Object Storage (COS), targeted at WeChat Mini-Program frontends and a minimal Node.js backend for signature generation.
- The project includes:
- src/: core SDK modules (upload logic, session, tasks, events)
- lib/: low-level utilities (crypto, request wrappers)
- server/: a small Node.js service (STS endpoint) for computing temporary credentials
- demo/ and demo-album/: sample Mini-Program apps illustrating SDK usage
- build.js + GitHub workflows: build and release pipeline

##### File structure
- Top-level: build scripts, CI configs (.github/), package.json
- src/: ES modules implementing SDK logic (advance, async, base, cos, event, session, task, tracker, util)
- lib/: helper libraries (base64, crypto, md5, request) packaged alongside src
- server/: sts.js – exposes an HTTP endpoint (/sts) that issues temporary credentials
- demo-album/ & demo/: WeChat Mini-Program directory structures, each with pages/, lib/ (including the built SDK), config, app.js/json, and sample code
- build.js: bundles src + lib into cos-wx-sdk-v5.js for consumption

##### Key points from the README
- Frontend (Mini-Program) must call getAuthorization → backend /sts endpoint → returns temporary SecretId/SecretKey/Token.
- SDK then uses returned credentials to call COS REST APIs (putObject, postObject, etc.).
- Demonstrations show image upload flow and policy retrieval.

##### How to represent this
a. Main components
1. Developer/CI Pipeline
- build.js, GitHub Actions → produces cos-wx-sdk-v5.js, publishes to npm or direct copy into Mini-Program.
2. Frontend Mini-Program
- UI pages (index, album, preview)
- cos-wx-sdk-v5.js (SDK core)
- getAuthorization callback → HTTP to backend
- COS API calls for file upload/download
3. Backend STS Service
- Node.js server (server/sts.js)
- Uses Tencent Cloud STS SDK to generate temporary credentials
4. External Service
- Tencent COS endpoint (object storage REST API)
b. Relationships & data flow
- Developer commits → CI/build → SDK artifact
- Mini-Program imports SDK → user triggers file selection → SDK.onUpload →
1) SDK invokes getAuthorization → HTTP POST to /sts → STS responds with credentials
2) SDK calls COS REST API (putObject, postObject) with credentials → COS stores file → returns status
c. Architectural patterns & design principles
- Modular layering:
- lib/ for low-level utilities
- src/ for high-level SDK logic
- server/ isolated to security-sensitive code (signature calculation)
- Callback injection (getAuthorization) allows users to integrate their own auth flows
- Demo apps are isolated, showing integration points without polluting SDK code
d. Technologies & frameworks
- JavaScript (ES6) for SDK logic
- Node.js Express-style service for STS endpoint
- WeChat Mini-Program framework (app.json, .wxml, .wxss)
- Babel (via .babelrc) and Prettier for code quality
- GitHub Actions for changelog automation and publishing

## Diagram (Mermaid)

```mermaid
graph TB
    %% Build & CI Pipeline
    subgraph "Build & CI Pipeline"
        direction TB
        CI["GitHub Actions"]:::pipeline
        BuildScript["build.js"]:::pipeline
        Changelog[".github/workflows/auto-changelog.yml"]:::pipeline
    end

    CI -->|runs| BuildScript
    CI -->|runs| Changelog

    %% SDK Modules
    subgraph "SDK Core Modules (src/)" 
        direction TB
        Advance["advance.js"]:::core
        Async["async.js"]:::core
        BaseSDK["base.js"]:::core
        COSLogic["cos.js"]:::core
        Event["event.js"]:::core
        Session["session.js"]:::core
        Task["task.js"]:::core
        Tracker["tracker.js"]:::core
        UtilSDK["util.js"]:::core
    end

    %% Low-level Utilities
    subgraph "Low-level Utilities (lib/)"
        direction TB
        Base64["base64.js"]:::util
        Crypto["crypto.js"]:::util
        MD5["md5.js"]:::util
        RequestUtil["request.js"]:::util
    end

    %% Backend STS Service
    subgraph "Backend STS Service"
        direction TB
        STSService["server/sts.js"]:::backend
    end

    %% Demo Mini-Program
    subgraph "Demo App (demo/)"
        direction TB
        DemoAppJS["app.js"]:::demo
        DemoAppJSON["app.json"]:::demo
        DemoAppWXSS["app.wxss"]:::demo
        DemoConfig["config.js"]:::demo
        DemoSDK["cos-wx-sdk-v5.js"]:::demo
        DemoAuth["cos-auth.js"]:::demo
        subgraph "Pages"
            direction TB
            DemoIndexJS["pages/index/index.js"]:::demo
            DemoIndexJSON["pages/index/index.json"]:::demo
            DemoIndexWXML["pages/index/index.wxml"]:::demo
            DemoIndexWXSS["pages/index/index.wxss"]:::demo
        end
    end

    %% Demo-album Mini-Program
    subgraph "Demo-Album App (demo-album/)"
        direction TB
        AlbumAppJS["app.js"]:::demo
        AlbumAppJSON["app.json"]:::demo
        AlbumAppWXSS["app.wxss"]:::demo
        AlbumConfig["config.js"]:::demo
        AlbumSDK["cos-wx-sdk-v5.js"]:::demo
        AlbumAPI["api.js"]:::demo
        AlbumCosLib["cos.js"]:::demo
        AlbumReqLib["request.js"]:::demo
        AlbumUtilLib["util.js"]:::demo
        subgraph "Pages"
            direction TB
            AlbumPageAlbum["pages/album/album.js"]:::demo
            AlbumPageIndex["pages/index/index.js"]:::demo
            AlbumPagePreview["pages/preview/preview.js"]:::demo
        end
    end

    %% External COS
    COS["Tencent COS REST API"]:::cloud

    %% Connections: Build to SDK modules (artifact)
    BuildArtifact["cos-wx-sdk-v5.js (build output)"]:::pipeline
    BuildScript -->|bundles src + lib| BuildArtifact
    BuildArtifact -->|imported into| DemoSDK
    BuildArtifact -->|imported into| AlbumSDK

    %% Runtime flow demo app
    DemoAppJS -->|"uses SDK"| BuildArtifact
    DemoIndexJS -->|trigger upload| BuildArtifact
    BuildArtifact -->|"getAuthorization callback"| STSService
    STSService -->|"returns credentials"| BuildArtifact
    BuildArtifact -->|"PUT/POST REST calls"| COS
    COS -->|"response"| BuildArtifact

    %% Runtime flow demo-album app
    AlbumAppJS -->|"uses SDK"| BuildArtifact
    AlbumPageAlbum -->|trigger upload| BuildArtifact
    BuildArtifact -->|"getAuthorization callback"| STSService
    STSService -->|"returns credentials"| BuildArtifact
    BuildArtifact -->|"PUT/POST REST calls"| COS
    COS -->|"response"| BuildArtifact

    %% Dependencies: SDK core uses utilities
    Advance --> BaseSDK
    Async --> BaseSDK
    BaseSDK --> RequestUtil
    COSLogic --> RequestUtil
    COSLogic --> Crypto
    Event --> Tracker
    Session --> Crypto
    Task --> Event
    Task --> Session
    UtilSDK --> Base64

    %% Click Events
    click BuildScript "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/build.js"
    click Changelog "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/.github/workflows/auto-changelog.yml"
    click Advance "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/src/advance.js"
    click Async "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/src/async.js"
    click BaseSDK "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/src/base.js"
    click COSLogic "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/src/cos.js"
    click Event "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/src/event.js"
    click Session "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/src/session.js"
    click Task "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/src/task.js"
    click Tracker "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/src/tracker.js"
    click UtilSDK "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/src/util.js"
    click Base64 "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/lib/base64.js"
    click Crypto "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/lib/crypto.js"
    click MD5 "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/lib/md5.js"
    click RequestUtil "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/lib/request.js"
    click STSService "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/server/sts.js"
    click DemoAppJS "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/demo/app.js"
    click DemoAppJSON "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/demo/app.json"
    click DemoAppWXSS "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/demo/app.wxss"
    click DemoConfig "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/demo/config.js"
    click DemoSDK "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/demo/lib/cos-wx-sdk-v5.js"
    click DemoAuth "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/demo/lib/cos-auth.js"
    click DemoIndexJS "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/demo/pages/index/index.js"
    click DemoIndexJSON "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/demo/pages/index/index.json"
    click DemoIndexWXML "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/demo/pages/index/index.wxml"
    click DemoIndexWXSS "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/demo/pages/index/index.wxss"
    click AlbumAppJS "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/demo-album/app.js"
    click AlbumAppJSON "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/demo-album/app.json"
    click AlbumAppWXSS "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/demo-album/app.wxss"
    click AlbumConfig "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/demo-album/config.js"
    click AlbumSDK "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/demo-album/lib/cos-wx-sdk-v5.js"
    click AlbumAPI "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/demo-album/lib/api.js"
    click AlbumCosLib "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/demo-album/lib/cos.js"
    click AlbumReqLib "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/demo-album/lib/request.js"
    click AlbumUtilLib "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/demo-album/lib/util.js"
    click AlbumPageAlbum "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/demo-album/pages/album/album.js"
    click AlbumPageIndex "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/demo-album/pages/index/index.js"
    click AlbumPagePreview "https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/demo-album/pages/preview/preview.js"

    %% Styles
    classDef pipeline fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef util fill:#87CEEB,stroke:#333,stroke-width:1px
    classDef backend fill:#B0C4DE,stroke:#333,stroke-width:1px
    classDef demo fill:#98FB98,stroke:#333,stroke-width:1px
    classDef cloud fill:#FFA500,stroke:#333,stroke-width:1px
```
