# vikiboss/r2-web architecture

> Architecture diagram of the GitHub repository vikiboss/r2-web, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vikiboss/r2-web
- Repository: https://github.com/vikiboss/r2-web

## Overview

##### 项目类型与目的（先定“画什么层级”）
从 README + 文件树判断：这是一个**纯前端（零后端）**的 Cloudflare R2（S3 API 兼容）文件管理器/图床工具，运行在浏览器里，直接用用户填写的凭证调用 R2 API。
因此系统设计图不要画“后端服务/数据库”，核心应该画清楚：

- **静态站点/PWA**如何交付到浏览器
- 浏览器端的**模块分层（UI / 业务 / R2 API 适配 / 缓存 / 配置）**
- 与 **Cloudflare R2（S3 API）** 的交互（含 AWS4 签名、CORS）
- 本地能力：**localStorage**、WASM 图片压缩、请求缓存、预览渲染
- 外部可选服务：比如 README 提到的 Tinify（如果代码里实现了“云压缩”开关，也要作为可选外部依赖画出来）

##### 顶层交付/工程与部署
- `src/index.html`：入口 HTML（大概率含 import maps / 脚本入口）
- `src/main.js`：主入口（启动应用、初始化 UI/配置/i18n 等）
- `src/manifest.json`：PWA 清单
- `wrangler.jsonc`：强烈暗示部署在 Cloudflare 生态（Pages/Workers 静态资源或相关配置）
- `package.json`、`pnpm-lock.yaml`：依赖只用于开发/类型提示，但也能用来标注关键第三方库（aws4fetch/dayjs/jsquash/qrcode）
- `.github/workflows/release.yaml` + `scripts/release.mts` + `bump.config.ts`：发布流水线（如果你要画“DevOps/Release 架构图”可单独一张）

##### 前端模块（src/js 是你画“组件图”的依据）
按文件名几乎可以直接抽象出模块职责：

- `src/js/app.js`：应用总控/路由式状态机（主协调者）
- `src/js/ui-manager.js`：UI 组件装配、对话框、提示、主题等
- `src/js/file-explorer.js`：目录浏览/列表分页/排序/懒加载缩略图（核心交互之一）
- `src/js/file-operations.js`：重命名/移动/复制/删除等操作编排（业务层）
- `src/js/upload-manager.js`：拖拽/粘贴/选择上传 + 进度/队列（业务层）
- `src/js/file-preview.js`：图片/音视频/文本预览与渲染（本地渲染能力）
- `src/js/r2-client.js`：R2(S3) API 访问层（HTTP + AWS4 签名 + 请求封装）
- `src/js/config-manager.js`：凭证/桶配置管理、localStorage 持久化、配置分享（链接/二维码）
- `src/js/i18n.js`：多语言资源与切换
- `src/js/constants.js`、`src/js/utils.js`：公共常量与工具（节流、防抖、缓存 key、格式化等）

##### 样式与静态资源
- `src/css/*` + `src/style.css`：CSS layers / tokens / layout / components
- 这些一般不用在系统图里细画，但可在“前端内部”标注为 **UI Assets**。

##### 建议你画 3 张图（最准确且不会丢信息）

必须包含这些框与箭头：

- **User（Browser）**
- **R2 Web（Static Site + PWA, runs in browser）**
- **Cloudflare R2（S3-compatible API）**
- **Optional External Services**（如果有：Tinify；如果没有实现就不要硬画）
- **Local Browser Storage**（localStorage / Cache）

关键箭头（要标注协议/关键约束）：
- Browser App → R2: `HTTPS (S3 API)` + `AWS4 Signature` + `CORS required`
- Browser App → localStorage: `store credentials/config (local only)`
- Browser App ↔ WASM codecs: `in-browser image compression`
- Browser App → (optional) Tinify: `HTTPS upload image for compression`（可选路径）

> 这张图的目的：澄清“零后端”，数据直连 R2，安全边界在浏览器与 R2。

这张图强调“站点如何被交付到浏览器”：

- **Static Hosting**（Cloudflare Pages / 任意静态托管；由 `wrangler.jsonc` 暗示 Cloudflare）
- delivers: `index.html`, `main.js`, `src/js/*`, `css/*`, `manifest.json`, WASM assets（如果存在）
- **Client Runtime (Browser)**
- PWA install / offline（如果有 service worker 文件，树里没看到；若实际用浏览器缓存策略也可标“PWA manifest only”）
- Fetch to R2

> 这张图可以把“CI/CD release”作为旁路：GitHub Actions → Static Hosting（可选）。

用 `src/js/*` 直接作为组件盒子（越细越好，按你的要求“尽量多拆组件”）：

推荐分 4 个泳道/颜色：

##### Application/Orchestration
- `app.js`（初始化、事件总线/状态流、把 UI 与业务串起来）
- `i18n.js`（语言资源、切换触发 UI 刷新）

##### Domain/Business
- `upload-manager.js`（拖拽/粘贴上传、队列、进度、命名模板、压缩策略选择）
- `file-operations.js`（rename/move/copy/delete recursive、批量操作）

##### Infrastructure/Adapters
- `r2-client.js`（list/get/put/delete/head, presigned url, copy object；内部用 aws4fetch）
- `config-manager.js`（credentials, bucket, endpoint; localStorage; 分享链接/二维码）
- `utils.js` / `constants.js`（缓存、格式化、节流、防抖等）
- **WASM codecs**（来自 `@jsquash/*`：mozjpeg/oxipng/webp/avif）
- **Browser APIs**：`Fetch`, `Clipboard`, `Drag&Drop`, `localStorage`, `<dialog>`

数据流建议画成“命令链”：
- UI event → `app.js` → (upload/file-ops) → `r2-client.js` → R2
- `config-manager.js` 提供签名所需配置给 `r2-client.js`
- `upload-manager.js` → (optional) `WASM compression` → `r2-client.putObject`
- `file-explorer.js` → `r2-client.list` → 渲染
- `file-preview.js` → `r2-client.get`/`signedUrl` → `<img>/<video>/<audio>/<pre>`

##### 必须强调的架构事实
- **无后端**：不存在你方服务器处理数据；所有操作发生在浏览器与 R2 之间
- **安全边界**：凭证只在 `localStorage`；风险点是“配置分享链接/二维码”携带敏感信息
- **AWS4 签名**：`aws4fetch` 作为关键依赖，建议在 `r2-client` 旁边显式标注
- **CORS 是前置条件**：README 里明确需要配置 R2 桶 CORS；在 Context 图用醒目注释
- **WASM 本地压缩**：图里把“压缩发生在客户端”画成独立节点，避免被误解为服务器处理

##### 建议标注的运行时“状态/缓存”
- `Request Cache`（README 提到请求缓存；可能在 `utils.js` 或 `r2-client.js` 做了缓存）
- `Pagination/Lazy loading`（file-explorer 的核心性能策略）
- `Throttling/debouncing`（性能策略）

##### 针对该项目类型（纯前端工具）的“画图要点”
与常见全栈不同，本项目的重点不是 API Gateway / DB schema，而是：

- **浏览器端分层**：UI/业务/适配器要清晰
- **外部依赖的协议细节**：S3 API + AWS4 + CORS
- **本地能力**：WASM、localStorage、剪贴板、拖拽、PWA manifest
- **风险点**：凭证与分享链接（可以在图上加 Security Notes）

##### 画图规范（让它“可读且可审”）
- 每个组件框写：**名称 + 文件名**（例如：`R2 Client (src/js/r2-client.js)`）
- 每条箭头写：**动作/协议**（ListObjectsV2 / PutObject / DeleteObject / presigned URL / localStorage read/write）

##### 形状与颜色（强制你区分类型）
- 蓝色：Browser internal modules（src/js）
- 灰色：Browser APIs（Fetch/localStorage/Clipboard/WASM runtime）
- 橙色：External systems（Cloudflare R2、Tinify）
- 紫色：Delivery/Hosting（Static host, GitHub Actions）

##### 方向与层次
- 从左到右：User → Browser App → External R2
- 从上到下：UI → Orchestration → Domain → Infrastructure

##### 结合当前仓库，建议你在图里“点名”的技术/文件
- `r2-client.js` + `aws4fetch`：签名与请求封装（这是系统成立的关键）
- `config-manager.js` + `localStorage`：凭证与配置生命周期（安全重点）
- `upload-manager.js` + `@jsquash/* (WASM)`：本地压缩（性能/隐私卖点）
- `file-explorer.js` / `file-operations.js`：主要业务能力
- `manifest.json`：PWA（安装体验）
- `wrangler.jsonc`：部署与 Cloudflare 生态关联（容器图/交付图里体现）

##### 最后给你一个“可直接照着画”的组件清单（按边界拆到最大）
Browser App（R2 Web）
- Entry
- `index.html`
- `main.js`
- Orchestration
- `app.js`
- UI / Views
- `ui-manager.js`
- `file-explorer.js`
- `file-preview.js`
- CSS: `src/css/*`, `style.css`
- Domain
- `upload-manager.js`
- `file-operations.js`
- Infra
- `r2-client.js` (uses `aws4fetch`)
- `config-manager.js` (uses `localStorage`)
- `i18n.js`
- `utils.js`
- `constants.js`
- Local execution deps
- WASM image codecs (`@jsquash/*`)
- Browser APIs: Fetch/Clipboard/DragDrop/Dialog

External
- Cloudflare R2 (S3 API endpoints)
- Optional: Tinify (cloud compression) — only if实际实现
- Static hosting (Cloudflare Pages/Vercel/Netlify)

- GitHub Actions release workflow → deploy static assets

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% ============ Context (C4 L1) ============
  subgraph "Context (C4 L1) — Zero-backend R2 Web (runs fully in browser)"
    direction TB

    User["User<br/>(Web Browser)"]:::external

    subgraph "R2 Web (Static Site + PWA, Browser Runtime)"
      direction TB
      AppRuntime["Client App Runtime<br/>(in-browser)"]:::browser
      LocalStore[("Browser Storage<br/>localStorage / Cache")]:::browserapi
      WASM["WASM Image Codecs<br/>(@jsquash/*)"]:::browserapi
      BrowserAPIs["Browser APIs<br/>(Fetch / Clipboard / Drag&Drop / &lt;dialog&gt;)"]:::browserapi
    end

    R2["Cloudflare R2<br/>(S3-compatible API)"]:::external
    Tinify["Optional: Tinify API<br/>(Cloud Compression)"]:::externalOpt

    User -->|"uses"| AppRuntime
    AppRuntime -->|"HTTPS(S3API)+AWS4Sig+CORS"| R2
    AppRuntime -->|"read/write config(cred,bucket,endpoint)"| LocalStore
    AppRuntime <-->|"compress images(in-browser)"| WASM
    AppRuntime <-->|"UI interactions"| BrowserAPIs
    AppRuntime -.->|"optional cloud compress"| Tinify

    CORSNote["Note: R2 bucket must enable CORS<br/>for browser direct access"]:::note
    SecNote["Security Note: Credentials stored locally;<br/>sharing links/QR may expose secrets"]:::note

    AppRuntime --- CORSNote
    AppRuntime --- SecNote
  end

  %% ============ Delivery / Container (C4 L2) ============
  subgraph "Delivery & Runtime (C4 L2)"
    direction TB

    GitHub["GitHub Repo"]:::devops
    GHA["GitHub Actions<br/>Release Workflow"]:::devops
    ReleaseScripts["Release Automation<br/>(scripts/bump)"]:::devops
    StaticHost["Static Hosting<br/>(Cloudflare Pages or any static host)"]:::hosting

    Assets["Static Assets<br/>(index.html, main.js, src/js/*, css/*, manifest.json)"]:::hosting

    GitHub -->|"triggers"| GHA
    GHA -->|"runs"| ReleaseScripts
    GHA -->|"deploys"| StaticHost
    StaticHost -->|"serves"| Assets
    Assets -->|"loads"| AppRuntime
  end

  %% ============ Component Diagram (C4 L3) ============
  subgraph "Browser Internal Components (C4 L3) — src/js layered architecture"
    direction TB

    subgraph "Entry"
      direction TB
      IndexHTML["index.html<br/>(App Shell)"]:::entry
      MainJS["main.js<br/>(Bootstraps app)"]:::entry
    end

    subgraph "Presentation / UI Layer"
      direction TB
      UIManager["UI Manager<br/>(dialogs,notifications,theme)"]:::ui
      FileExplorer["File Explorer<br/>(tree,list,pagination,sorting,thumb lazy-load)"]:::ui
      FilePreview["File Preview<br/>(img/video/audio/text render)"]:::ui
      UIAssets["UI Assets<br/>(CSS layers/tokens/components)"]:::assets
    end

    subgraph "Application / Orchestration"
      direction TB
      AppJS["App Controller<br/>(state,coordination)"]:::app
      I18N["i18n<br/>(language resources/switch)"]:::app
    end

    subgraph "Domain / Business"
      direction TB
      UploadMgr["Upload Manager<br/>(drag/paste/queue/progress/compress strategy)"]:::domain
      FileOps["File Operations<br/>(rename/move/copy/delete,batch)"]:::domain
    end

    subgraph "Infrastructure / Adapters"
      direction TB
      ConfigMgr["Config Manager<br/>(credentials,bucket,endpoint,share link/QR)"]:::infra
      R2Client["R2 Client<br/>(S3 API wrapper + AWS4 signing entry)"]:::infra
      AWS4Fetch["aws4fetch<br/>(AWS4 Signature)"]:::lib
      Utils["utils<br/>(format,throttle/debounce,cache)"]:::infra
      Consts["constants"]:::infra
      ReqCache["Request Cache<br/>(list/get caching)"]:::infra
    end

    %% Boot / wiring
    IndexHTML -->|"loads"| MainJS
    MainJS -->|"initializes"| AppJS
    MainJS -->|"loads styles"| UIAssets
    MainJS -->|"init i18n"| I18N
    AppJS -->|"mount UI"| UIManager
    AppJS -->|"bind events"| FileExplorer
    AppJS -->|"bind events"| FilePreview
    AppJS -->|"orchestrates"| UploadMgr
    AppJS -->|"orchestrates"| FileOps

    %% Config & persistence
    ConfigMgr <-->|"read/write"| LocalStore
    AppJS -->|"load/save config"| ConfigMgr
    R2Client -->|"get creds/endpoint"| ConfigMgr

    %% R2 access + signing
    R2Client -->|"uses"| AWS4Fetch
    R2Client -->|"fetch HTTPS(S3API)"| R2
    R2Client <-->|"cache reads"| ReqCache
    ReqCache -->|"helpers"| Utils
    R2Client -->|"uses utils/consts"| Utils
    R2Client -->|"uses consts"| Consts

    %% File explorer & preview data flows
    FileExplorer -->|"ListObjectsV2"| R2Client
    FileExplorer -->|"pagination/lazy-load (throttle)"| Utils
    FilePreview -->|"GetObject/HeadObject/signed URL"| R2Client

    %% Upload & operations data flows
    UploadMgr -->|"Drag&Drop/Clipboard"| BrowserAPIs
    UploadMgr -->|"optional local compress"| WASM
    UploadMgr -->|"PutObject (multipart/stream)"| R2Client
    UploadMgr -.->|"optional cloud compress"| Tinify

    FileOps -->|"CopyObject/DeleteObject/PutObject"| R2Client

    %% UI interactions
    UIManager <-->|"dialogs,notifications,theme"| BrowserAPIs
    FileExplorer <-->|"UI events"| BrowserAPIs
    FilePreview <-->|"render to DOM"| BrowserAPIs
    I18N -->|"refresh UI strings"| UIManager
  end

  %% ============ Click Events (from component_mapping) ============
  click IndexHTML "https://github.com/vikiboss/r2-web/blob/main/src/index.html"
  click MainJS "https://github.com/vikiboss/r2-web/blob/main/src/main.js"
  click AppJS "https://github.com/vikiboss/r2-web/blob/main/src/js/app.js"
  click UIManager "https://github.com/vikiboss/r2-web/blob/main/src/js/ui-manager.js"
  click FileExplorer "https://github.com/vikiboss/r2-web/blob/main/src/js/file-explorer.js"
  click FileOps "https://github.com/vikiboss/r2-web/blob/main/src/js/file-operations.js"
  click UploadMgr "https://github.com/vikiboss/r2-web/blob/main/src/js/upload-manager.js"
  click FilePreview "https://github.com/vikiboss/r2-web/blob/main/src/js/file-preview.js"
  click R2Client "https://github.com/vikiboss/r2-web/blob/main/src/js/r2-client.js"
  click ConfigMgr "https://github.com/vikiboss/r2-web/blob/main/src/js/config-manager.js"
  click I18N "https://github.com/vikiboss/r2-web/blob/main/src/js/i18n.js"
  click Consts "https://github.com/vikiboss/r2-web/blob/main/src/js/constants.js"
  click Utils "https://github.com/vikiboss/r2-web/blob/main/src/js/utils.js"
  click UIAssets "https://github.com/vikiboss/r2-web/tree/main/src/css/"
  click UIAssets "https://github.com/vikiboss/r2-web/blob/main/src/style.css"
  click StaticHost "https://github.com/vikiboss/r2-web/blob/main/wrangler.jsonc"
  click GHA "https://github.com/vikiboss/r2-web/blob/main/.github/workflows/release.yaml"
  click ReleaseScripts "https://github.com/vikiboss/r2-web/blob/main/scripts/release.mts"
  click ReleaseScripts "https://github.com/vikiboss/r2-web/blob/main/bump.config.ts"
  click GitHub "https://github.com/vikiboss/r2-web/blob/main/package.json"

  %% ============ Styles ============
  classDef external fill:#ffedd5,stroke:#c2410c,color:#7c2d12,stroke-width:1.5px
  classDef externalOpt fill:#fff7ed,stroke:#f97316,color:#7c2d12,stroke-width:1.5px,stroke-dasharray: 5 4
  classDef browser fill:#dbeafe,stroke:#1d4ed8,color:#0f172a,stroke-width:1.5px
  classDef browserapi fill:#e5e7eb,stroke:#374151,color:#111827,stroke-width:1.2px
  classDef hosting fill:#ede9fe,stroke:#6d28d9,color:#111827,stroke-width:1.5px
  classDef devops fill:#f3e8ff,stroke:#7e22ce,color:#111827,stroke-width:1.3px
  classDef entry fill:#c7d2fe,stroke:#4338ca,color:#0f172a,stroke-width:1.3px
  classDef ui fill:#93c5fd,stroke:#1d4ed8,color:#0b1220,stroke-width:1.3px
  classDef assets fill:#bfdbfe,stroke:#1d4ed8,color:#0b1220,stroke-width:1.1px
  classDef app fill:#60a5fa,stroke:#1e3a8a,color:#0b1220,stroke-width:1.3px
  classDef domain fill:#38bdf8,stroke:#075985,color:#0b1220,stroke-width:1.3px
  classDef infra fill:#2563eb,stroke:#1e40af,color:#eff6ff,stroke-width:1.3px
  classDef lib fill:#1d4ed8,stroke:#0b2a6f,color:#eff6ff,stroke-width:1.2px
  classDef note fill:#fef9c3,stroke:#a16207,color:#713f12,stroke-width:1px
```
