# wintorse/copylink-dev architecture

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

- Interactive diagram: https://gitdiagram.com/wintorse/copylink-dev
- Repository: https://github.com/wintorse/copylink-dev

## Overview

##### Project Type and Purpose
- This is a browser extension (Chrome + Firefox) written in TypeScript/Vite.
- Its purpose is to let end users trigger keyboard shortcuts to copy Markdown-style links or Slack-formatted links from any web page, with site-specific title formatting and emoji support.

##### File Structure
- Top level:
- src/ — TypeScript source, split into popup logic, background scripts, content scripts, utilities, types
- .github/workflows — CI/CD for releases
- vite.config.js, tsconfig.json — build configuration
- In src/:
- src/popup/popup.ts — UI logic for the extension popup and settings page
- src/scripts/background.ts & background_firefox.ts — event listeners, command registration, central message router
- src/scripts/content.ts — injected script that lives in the web page context
- src/scripts/commands.ts — maps keyboard shortcuts to actions
- src/scripts/copyTextLink.ts & formattedTitleRetriever.ts & getEmojiName.ts — core business logic modules
- src/utils/notification.ts & toast.ts — helper modules for user notifications
- src/types — shared type definitions and constants

##### Extract Key Insights from the README
- Core features: Copy link, copy link with Slack emoji, copy title.
- Site support: Google Workspace, GitHub, Jira, Asana, Backlog, Redmine, plus custom sites via regex.
- Installation flows for Chrome vs Firefox (background_firefox.ts differs slightly).
- Keyboard commands configurable in the browser settings.

##### Main Components
a. Manifest & Static Assets (public/)
b. Popup UI
c. Background Script (Chrome & Firefox variants)
d. Content Script (in-page)
e. Business Logic Modules (formattedTitleRetriever, copyTextLink, getEmojiName)
f. Utility Modules (notification, toast)
g. External Targets: Web pages (various sites), Clipboard API, Browser Commands API

##### Relationships & Interactions
- Popup sends/receives messages to/from Background via browser.runtime.sendMessage.
- User triggers keyboard shortcut → Browser Commands API invokes Background Script handler.
- Background Script injects or communicates with Content Script in active tab.
- Content Script uses formattedTitleRetriever & getEmojiName to build the link string.
- Result is sent back to Background, which writes to the Clipboard via Clipboard API or uses background.execClipboard.
- Notification or toast UI (via content script injection or popup) confirms success.
- Settings stored via chrome.storage (not in file tree, but implied).

##### Architectural Patterns & Design Principles
- Modular separation: UI layer (popup), orchestration layer (background), domain logic (scripts/*), helpers (utils/*).
- Message-driven: All interactions use the browser’s messaging framework.
- Platform abstraction: background.ts vs background_firefox.ts.
- Build pipeline: Vite bundles TS → dist/ for Chrome and Firefox.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Developer Toolchain"
        Vite["vite.config.js"]:::dev
        TS["tsconfig.json"]:::dev
        CI[".github/workflows/release.yml"]:::dev
    end
    subgraph "Manifest & Static Assets"
        ManifestC["manifest.json"]:::manifest
        ManifestF["manifest_firefox.json"]:::manifest
        PopupHTML["popup.html"]:::manifest
        StylesDir["styles/"]:::manifest
        Locales["_locales/"]:::manifest
        Images["images/"]:::manifest
    end
    subgraph "Popup UI"
        PopupTS["src/popup/popup.ts"]:::ui
        PopupCSS["popup.css"]:::ui
    end
    subgraph "Background Scripts"
        BGChrome["background.ts"]:::background
        BGFirefox["background_firefox.ts"]:::background
        Commands["commands.ts"]:::background
    end
    subgraph "Content Script"
        Content["content.ts"]:::content
    end
    subgraph "Business Logic Modules"
        CopyLink["copyTextLink.ts"]:::business
        TitleFmt["formattedTitleRetriever.ts"]:::business
        Emoji["getEmojiName.ts"]:::business
    end
    subgraph "Utilities & Types"
        Notification["notification.ts"]:::util
        Toast["toast.ts"]:::util
        SharedTypes["types.ts"]:::util
        Constants["constants.ts"]:::util
    end
    subgraph "External Resources / APIs"
        WebPage["Web Page Context"]:::external
        Clipboard["Clipboard API"]:::external
        BrowserCmd["Browser Commands API"]:::external
        ChromeStorage["chrome.storage"]:::external
    end

    Vite --> ManifestC
    Vite --> BGChrome
    Vite --> BGFirefox
    Vite --> PopupTS
    Vite --> Content
    CI --> Vite
    TS --> Vite

    ManifestC --> PopupHTML
    ManifestC --> BGChrome
    ManifestF --> BGFirefox
    ManifestC --> Content

    PopupHTML --> PopupTS
    PopupCSS --> PopupHTML

    PopupTS -->|"sendMessage"| BGChrome
    PopupTS -->|"sendMessage"| BGFirefox
    PopupTS -->|"read/write"| ChromeStorage

    BrowserCmd -->|"trigger shortcut"| BGChrome
    BrowserCmd -->|"trigger shortcut"| BGFirefox

    BGChrome --> Commands
    BGFirefox --> Commands

    BGChrome -->|"message to tab"| Content
    BGFirefox -->|"message to tab"| Content

    Content --> CopyLink
    Content --> TitleFmt
    Content --> Emoji
    Content --> Notification
    Content --> Toast

    CopyLink --> SharedTypes
    TitleFmt --> SharedTypes
    Emoji --> SharedTypes

    BGChrome --> Clipboard
    BGFirefox --> Clipboard

    PopupTS --> Notification
    PopupTS --> Toast

    PopupTS --> SharedTypes

    SharedTypes --> Constants

    Content --> WebPage
    WebPage --> Content

    classDef dev fill:#f9f,stroke:#333,stroke-width:1px
    classDef manifest fill:#ff9,stroke:#333,stroke-width:1px
    classDef ui fill:#9f9,stroke:#333,stroke-width:1px
    classDef background fill:#9cf,stroke:#333,stroke-width:1px
    classDef content fill:#fc9,stroke:#333,stroke-width:1px
    classDef business fill:#cfc,stroke:#333,stroke-width:1px
    classDef util fill:#ccf,stroke:#333,stroke-width:1px
    classDef external fill:#eee,stroke:#333,stroke-width:1px

    click Vite "https://github.com/wintorse/copylink-dev/blob/main/vite.config.js"
    click TS "https://github.com/wintorse/copylink-dev/blob/main/tsconfig.json"
    click CI "https://github.com/wintorse/copylink-dev/blob/main/.github/workflows/release.yml"
    click ManifestC "https://github.com/wintorse/copylink-dev/blob/main/public/manifest.json"
    click ManifestF "https://github.com/wintorse/copylink-dev/blob/main/public/manifest_firefox.json"
    click PopupHTML "https://github.com/wintorse/copylink-dev/blob/main/public/popup.html"
    click StylesDir "https://github.com/wintorse/copylink-dev/tree/main/public/styles/"
    click Locales "https://github.com/wintorse/copylink-dev/tree/main/public/_locales/"
    click Images "https://github.com/wintorse/copylink-dev/tree/main/public/images/"
    click PopupTS "https://github.com/wintorse/copylink-dev/blob/main/src/popup/popup.ts"
    click PopupCSS "https://github.com/wintorse/copylink-dev/blob/main/public/styles/popup.css"
    click BGChrome "https://github.com/wintorse/copylink-dev/blob/main/src/scripts/background.ts"
    click BGFirefox "https://github.com/wintorse/copylink-dev/blob/main/src/scripts/background_firefox.ts"
    click Commands "https://github.com/wintorse/copylink-dev/blob/main/src/scripts/commands.ts"
    click Content "https://github.com/wintorse/copylink-dev/blob/main/src/scripts/content.ts"
    click CopyLink "https://github.com/wintorse/copylink-dev/blob/main/src/scripts/copyTextLink.ts"
    click TitleFmt "https://github.com/wintorse/copylink-dev/blob/main/src/scripts/formattedTitleRetriever.ts"
    click Emoji "https://github.com/wintorse/copylink-dev/blob/main/src/scripts/getEmojiName.ts"
    click Notification "https://github.com/wintorse/copylink-dev/blob/main/src/utils/notification.ts"
    click Toast "https://github.com/wintorse/copylink-dev/blob/main/src/utils/toast.ts"
    click SharedTypes "https://github.com/wintorse/copylink-dev/blob/main/src/types/types.ts"
    click Constants "https://github.com/wintorse/copylink-dev/blob/main/src/types/constants.ts"
```
