# eltonchou/twittermediaharvest architecture

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

- Interactive diagram: https://gitdiagram.com/eltonchou/twittermediaharvest
- Repository: https://github.com/eltonchou/twittermediaharvest

## Overview

##### Main Components

- Extension UI:
- Popup, options page, and other UI components (found in src/pages and its subdirectories).
- That these components use React (files like Options.tsx, Popup.tsx) and incorporate common UI components such as side menus and controls.

- Content Script:
- Content_script module which directly interacts with Twitter’s UI.
- Various observer modules (e.g., TweetDeckBetaObserver, TwitterMediaObserver) and core functionality (the Harvester classes) that scan the page, detect media elements, and relay commands to the backend parts.

- Backend/Logic:
- “src/backend” folder components. Break these into sub-components:
▪ Client modules, commands, and repositories (for cookie, credentials, and downloads).
▪ Downloads subsystem: modules and use cases (downloading media files, progress tracking, recording download history).
▪ Settings/Configuration: modules for download settings, filename settings, and Twitter API settings.
▪ Notifications: modules for generating and handling notifications.
▪ API integrations: twitterApi modules for interfacing with Twitter’s endpoints.
- Showing data flows such as:
▪ content_script → backend commands/useCases (for download actions)
▪ backend interactions with local storage and IndexedDB (via repositories).

- Service Workers:
- Their role in communicating between the extension’s UI/content scripts and the backend.

- Libraries and Utilities:
- Core support modules from src/libs (for browser API interactions, IndexedDB management, and proxy support).
- Shared utilities in both backend and content script layers (like data checkers and i18n functions).

- Localization:
- _locales directory as a support layer for internationalization – ensuring the UI and notifications correctly reflect multiple languages (en, ja, zh).

##### Relationships and Interactions

- Data Flow:
- Interaction between the Extension UI and the backend (via state management and React stores in src/pages/stores) for user-initiated actions such as triggering a download or modifying settings.
- Service workers as intermediaries that listen to events (e.g., browser messages, API callbacks) and trigger subsequent backend operations.

- Dependencies:
- Dependencies where backend functionalities rely on third-party APIs (e.g., Twitter API integration in twitterApi/useCases).
- Build and configuration components (webpack.config.js, babel.config.js, tsconfig.json) as peripheral elements that inform deployment but aren’t part of the runtime architecture.

##### Architectural Patterns

- Separation of Concerns:
- Clearly separate the presentation layer (UI), content scripts (browser interactions), backend logic, and background/service worker responsibilities.

- Modular Design:

- Use of Repositories and UseCases:
- Backend components follow a pattern where repositories handle low-level data persistence (e.g., IndexedDB for download histories) and use case modules encapsulate business logic. Represent these interactions explicitly between “Repositories” and “Use Cases.”

##### Final Checklist for the Principal Software Engineer

- Adding notes on key technologies (React for UI, TypeScript for module development, browser-specific APIs in service workers, etc.) to provide additional context.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Extension UI
    subgraph "Extension UI"
        UI1("Popup (React)"):::ui
        UI2("Options (React)"):::ui
        UI3("UI Components"):::ui
    end

    %% Content Script
    subgraph "Content Script"
        CS1("Media Harvester (Core)"):::content
        CS2("TwitterMediaObserver"):::content
        CS3("Additional Observers & Utils"):::content
    end

    %% Backend/Logic
    subgraph "Backend/Logic"
        RM("Repositories & Client Modules"):::backend
        DU("Download Use Cases"):::backend
        SET("Settings & Configuration"):::backend
        NOTIF("Notifications"):::backend
        API("Twitter API Integrations"):::backend
    end

    %% Service Workers
    subgraph "Service Workers"
        SW1("Chrome Initialization"):::serviceWorker
        SW2("Firefox Initialization"):::serviceWorker
        SW3("Edge Initialization"):::serviceWorker
    end

    %% Libraries & Utilities
    subgraph "Libraries & Utilities"
        LIB("Browser APIs & IndexedDB Management"):::utility
        UTIL("Shared Utilities"):::utility
    end

    %% Localization
    subgraph "Localization"
        LOC("Internationalization (_locales)"):::localization
    end

    %% Data Flow and Interactions
    CS1 -->|"Triggers"| RM
    CS1 -->|"InitiatesDownload"| DU
    CS2 -->|"DetectsMedia"| CS1
    UI1 -->|"UserAction"| RM
    UI2 -->|"UserSettings"| SET
    UI3 -->|"SyncsUI"| RM

    RM -->|"PersistsData"| LIB
    DU -->|"ProgressTracking"| LIB
    SET -->|"ConfigUpdates"| LIB
    NOTIF -->|"SendsAlerts"| UI3
    API -->|"DataFetch"| RM
    LIB -->|"ProvidesSupport"| UTIL
    RM -->|"Uses"| UTIL

    SW1 -->|"HandlesBackgroundTasks"| RM
    SW2 -->|"HandlesBackgroundTasks"| RM
    SW3 -->|"HandlesBackgroundTasks"| RM

    %% Click Events
    click UI1 "https://github.com/eltonchou/twittermediaharvest/blob/main/src/pages/app/Popup.tsx"
    click UI2 "https://github.com/eltonchou/twittermediaharvest/blob/main/src/pages/app/Options.tsx"
    click UI3 "https://github.com/eltonchou/twittermediaharvest/tree/main/src/pages/components"
    click CS1 "https://github.com/eltonchou/twittermediaharvest/blob/main/src/content_script/core/Harvester.ts"
    click CS2 "https://github.com/eltonchou/twittermediaharvest/blob/main/src/content_script/observers/TwitterMediaObserver.ts"
    click RM "https://github.com/eltonchou/twittermediaharvest/tree/main/src/backend/client"
    click DU "https://github.com/eltonchou/twittermediaharvest/tree/main/src/backend/downloads"
    click SET "https://github.com/eltonchou/twittermediaharvest/tree/main/src/backend/settings"
    click NOTIF "https://github.com/eltonchou/twittermediaharvest/tree/main/src/backend/notifications"
    click API "https://github.com/eltonchou/twittermediaharvest/tree/main/src/backend/twitterApi"
    click SW1 "https://github.com/eltonchou/twittermediaharvest/blob/main/src/service_worker/chrome/initialization.ts"
    click SW2 "https://github.com/eltonchou/twittermediaharvest/blob/main/src/service_worker/firefox/initialization.ts"
    click SW3 "https://github.com/eltonchou/twittermediaharvest/blob/main/src/service_worker/edge/initialization.ts"
    click LIB "https://github.com/eltonchou/twittermediaharvest/tree/main/src/libs"
    click UTIL "https://github.com/eltonchou/twittermediaharvest/tree/main/src/backend/utils"
    click LOC "https://github.com/eltonchou/twittermediaharvest/tree/main/src/_locales"

    %% Styles
    classDef ui fill:#f5e1da,stroke:#333,stroke-width:2px;
    classDef content fill:#d4e8d4,stroke:#333,stroke-width:2px;
    classDef backend fill:#dae8fc,stroke:#333,stroke-width:2px;
    classDef serviceWorker fill:#fff2cc,stroke:#333,stroke-width:2px;
    classDef utility fill:#ead1dc,stroke:#333,stroke-width:2px;
    classDef localization fill:#fce5cd,stroke:#333,stroke-width:2px;
```
