# whale4113/cloud-document-converter architecture

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

- Interactive diagram: https://gitdiagram.com/whale4113/cloud-document-converter
- Repository: https://github.com/whale4113/cloud-document-converter

## Overview

##### Project type and purpose
- This is a browser‐extension project (“Cloud Document Converter”) within a pnpm/turbo monorepo.
- Its goal is to let end‐users on Lark Docs pages download or copy the document content as Markdown.

##### File structure
- Top‐level monorepo config:
- pnpm-workspace.yaml, turbo.json – orchestrate multi‐package builds.
- .github/workflows – CI, releases, dependency updates.
- apps/chrome-extension – the extension codebase:
- popup.html + popup.js – extension UI.
- background.ts – background script handles heavy lifting (file generation, downloads).
- content.ts – content script injected into Lark Docs pages.
- src/common – shared utilities (i18n, messaging, notifications).
- scripts/… – build helpers (version bump, cross‐browser build).
- rollup.config.js + tsconfig*.json – build pipeline for web, Node, extension.
- packages/common – shared utility library.
- packages/lark – core Lark‐doc‐to‐Markdown parsing and file handling.
- other packages – eslint-config, rollup-config, typescript-config.

##### README for architectural hints
- Features emphasize two flows: “Download as Markdown” and “Copy as Markdown.”
- Interactions happen on Lark Docs pages, then pass through extension scripts, through the lark parser, and finally to user.

a. Main components
- Browser extension UI (popup)
- Content Script (injected into Lark Docs page)
- Background Script (orchestrator)
- Core Parsing Library (packages/lark)
- Shared Utility Library (packages/common)
- Build & Tooling (pnpm, turbo, Rollup, scripts)
- External Systems: Lark Docs web page, Lark file/CDN endpoints, Chrome/Edge/Firefox stores
- CI/CD pipeline (GitHub Actions)
b. Relationships and interactions
1. User opens the extension popup → UI triggers a message.
2. Popup communicates with Background Script via chrome.runtime.
3. Background Script may ask Content Script to scrape the current Lark Docs DOM or fetch docx via Lark API.
4. Content Script returns raw document data to Background.
5. Background invokes packages/lark to convert to Markdown (using shared/common utils).
6. Background triggers file download or writes to clipboard.
7. Build pipeline (Rollup, turbo) compiles TypeScript, bundles packages, outputs extension artifact.
8. CI/CD publishes to extension stores.
c. Architectural patterns and principles
- Separation of concerns: UI / orchestration / parsing / utilities
- Message‐passing micro‐frontend (content vs. background vs. popup)
- Monorepo workspace – code reuse and consistent configs
- Layered build pipeline – each package has its own Rollup and tsconfig but shares root tooling
d. Key technologies and libraries
- TypeScript, Rollup, pnpm workspaces, turborepo
- Chrome Extension APIs (runtime messaging, downloads, storage)
- packages/lark for parsing docx and DOM → Markdown
- packages/common for shared utilities (DOM, image handling, time)
- GitHub Actions for CI, GitHub Releases, Dependabot

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Extension Runtime
    subgraph "Extension Runtime"
        direction TB
        subgraph "UI"
            direction TB
            PopupHTML["popup.html"]:::runtime
            PopupJS["popup.js"]:::runtime
        end
        ContentScript["Content Script\n(content.ts)"]:::runtime
        BackgroundScript["Background Script\n(background.ts)"]:::runtime
    end

    %% Processing Layer
    subgraph "Processing Layer"
        direction TB
        subgraph "Core Parsing Library"
            direction TB
            LarkIndex["index.ts"]:::lib
            LarkDocx["docx.ts"]:::lib
            LarkFile["file.ts"]:::lib
        end
        subgraph "Utility Library"
            direction TB
            CommonIndex["index.ts"]:::lib
            CommonDOM["dom.ts"]:::lib
            CommonUtils["utils.ts"]:::lib
        end
    end

    %% Build & Deployment
    subgraph "Build & Deployment"
        direction TB
        subgraph "Build Pipeline"
            direction TB
            RollupExt["rollup.config.js"]:::build
            RollupPkg["packages/rollup-config/lib.js"]:::build
            PnpmYaml["pnpm-workspace.yaml"]:::build
            TurboCfg["turbo.json"]:::build
        end
        subgraph "CI/CD Pipeline"
            direction TB
            CI["ci.yml"]:::build
            Releases["create-github-releases.yml"]:::build
        end
        Stores["Extension Stores"]:::external
    end

    ExternalDocs["Lark Docs Page"]:::external

    %% Connections
    PopupHTML -->|"trigger message"| BackgroundScript
    PopupJS -->|"trigger message"| BackgroundScript
    BackgroundScript -->|"inject or message"| ContentScript
    ContentScript -->|"scrapes DOM"| BackgroundScript
    BackgroundScript -->|"parse"| LarkIndex
    LarkIndex --> LarkDocx
    LarkIndex --> LarkFile
    LarkIndex --> CommonIndex
    CommonIndex --> CommonDOM
    CommonIndex --> CommonUtils
    BackgroundScript -->|"download/copy"| Stores
    RollupExt -->|"bundle"| BackgroundScript
    RollupPkg -->|"config share"| RollupExt
    PnpmYaml --> TurboCfg
    TurboCfg --> RollupExt
    CI -->|"publish"| Stores
    Releases -->|"release"| Stores
    ExternalDocs -->|"page context"| ContentScript

    %% Click Events
    click PopupHTML "https://github.com/whale4113/cloud-document-converter/blob/main/apps/chrome-extension/popup.html"
    click PopupJS "https://github.com/whale4113/cloud-document-converter/blob/main/apps/chrome-extension/popup.js"
    click ContentScript "https://github.com/whale4113/cloud-document-converter/blob/main/apps/chrome-extension/src/content.ts"
    click BackgroundScript "https://github.com/whale4113/cloud-document-converter/blob/main/apps/chrome-extension/src/background.ts"
    click LarkIndex "https://github.com/whale4113/cloud-document-converter/blob/main/packages/lark/src/index.ts"
    click LarkDocx "https://github.com/whale4113/cloud-document-converter/blob/main/packages/lark/src/docx.ts"
    click LarkFile "https://github.com/whale4113/cloud-document-converter/blob/main/packages/lark/src/file.ts"
    click CommonIndex "https://github.com/whale4113/cloud-document-converter/blob/main/packages/common/src/index.ts"
    click CommonDOM "https://github.com/whale4113/cloud-document-converter/blob/main/packages/common/src/dom.ts"
    click CommonUtils "https://github.com/whale4113/cloud-document-converter/blob/main/packages/common/src/utils.ts"
    click RollupExt "https://github.com/whale4113/cloud-document-converter/blob/main/apps/chrome-extension/rollup.config.js"
    click RollupPkg "https://github.com/whale4113/cloud-document-converter/blob/main/packages/rollup-config/lib.js"
    click PnpmYaml "https://github.com/whale4113/cloud-document-converter/blob/main/pnpm-workspace.yaml"
    click TurboCfg "https://github.com/whale4113/cloud-document-converter/blob/main/turbo.json"
    click CI "https://github.com/whale4113/cloud-document-converter/blob/main/.github/workflows/ci.yml"
    click Releases "https://github.com/whale4113/cloud-document-converter/blob/main/.github/workflows/create-github-releases.yml"

    %% Styles
    classDef runtime fill:#D6EAF8,stroke:#3498DB,color:#1B4F72
    classDef lib fill:#D5F5E3,stroke:#27AE60,color:#145A32
    classDef build fill:#FCF3CF,stroke:#F1C40F,color:#7D6608
    classDef external fill:#F2F3F4,stroke:#85C1E9,color:#1B2631
```
