# sindresorhus/refined-twitter architecture

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

- Interactive diagram: https://gitdiagram.com/sindresorhus/refined-twitter
- Repository: https://github.com/sindresorhus/refined-twitter

## Overview

##### Project type and purpose
- This is a browser extension (Chrome/Opera/Firefox) named “Refined Twitter.”
- Purpose: run in the user’s browser, inject UI-improving features into twitter.com pages, provide an options UI, and manage settings—all with zero external backend.

##### Key architectural components
a. Build-time pipeline
- Webpack (webpack.config.js)
- Input: source/ (JS modules, CSS, HTML, manifest.json)
- Output: distribution/ folder loaded into the browser.
b. Runtime components
1. Manifest (manifest.json)
- Declares permissions, content scripts, background script, options page.
2. Background script (background.js)
- Runs persistently (or as an event page/service worker).
- Listens for extension events, routes messages, stores/retrieves settings.
3. Content script (content.js)
- Injected into twitter.com pages.
- Imports source/features/*.js to modify the DOM, apply CSS, listen for keyboard shortcuts.
4. Options page (options.html + options.js)
- UI for toggling features, persisted in chrome.storage.
5. Shared utilities (source/libs/utils.js)
6. Styles (source/style/*.css)
c. Data storage
- chrome.storage.local / chrome.storage.sync for user preferences.

##### Relationships & interactions
- At install/load:
manifest → registers background script, content scripts, options page.
- On Twitter page load:
content.js ← manifest
→ imports and executes each feature module → manipulates page DOM & injects CSS
↔ background.js via chrome.runtime.sendMessage / onMessage (for e.g. reading settings)
- Options UI ↔ background.js (read/write settings)
- background.js ↔ chrome.storage (persist feature toggles)

##### Architectural patterns & design principles
- Modular feature-based design: each feature in source/features is a self-contained module.
- Separation of concerns:
- Background for messaging & storage
- Content for page DOM interaction
- Options for UI/configuration
- Single-page HTML for options; CSS scoped per content vs. options context.

##### Detail level
- Manifest at the center of build/runtime boundary.
- Which files live in source/, which get bundled, and which end up in distribution.
- Essential flows (injection, messaging, storage), but you don’t need to show every single feature file—group them logically.

##### Final checklist
- Components: manifest, background script, content script, feature modules, options page, storage, build pipeline.
- Clear labels & legends.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build Time
    subgraph "Build Time"
        direction TB
        src["source/"]:::code
        webpack["Webpack<br/>(webpack.config.js)"]:::build
        dist["distribution/"]:::code
        src --> webpack --> dist
    end

    %% Runtime
    subgraph "Runtime"
        direction TB
        manifest["manifest.json"]:::code
        background["background.js"]:::code
        content["content.js"]:::code
        optionsPage["Options Page<br/>(options.html + options.js)"]:::ui
        featuresFolder["Features Folder"]:::code

        manifest --> background
        manifest --> content
        manifest --> optionsPage

        content --> featuresFolder
        featuresFolder --> index["index.js"]:::code

        content -->|"message"| background
        optionsPage -->|"message"| background
        background -->|"chrome.storage API"| storage
    end

    %% Features Modules
    subgraph "Feature Modules" 
        direction TB
        autoLoad["Auto-load new tweets"]:::code
        cleanNav["Clean navbar dropdown"]:::code
        codeHighlight["Code highlight"]:::code
        disableColors["Disable custom colors"]:::code
        hideFollow["Hide follow tweets"]:::code
        hideMissed["Hide “in case you missed” notifications"]:::code
        hideLikeTweets["Hide like tweets"]:::code
        hidePromoted["Hide promoted tweets"]:::code
        hideRetweetBtn["Hide retweet buttons"]:::code
        hideRetweets["Hide retweets"]:::code
        hideTrends["Hide trends & who to follow"]:::code
        imgAlt["Image alternatives"]:::code
        inlineCode["Inline code styling"]:::code
        inlineInsta["Inline Instagram photos"]:::code
        kbShortcuts["Keyboard shortcuts"]:::code
        likesNav["Likes button in navbar"]:::code
        mentions["Mentions highlight"]:::code
        preserveMsgs["Preserve text messages"]:::code
        removeHeader["Remove profile header"]:::code

        featuresFolder --> autoLoad
        featuresFolder --> cleanNav
        featuresFolder --> codeHighlight
        featuresFolder --> disableColors
        featuresFolder --> hideFollow
        featuresFolder --> hideMissed
        featuresFolder --> hideLikeTweets
        featuresFolder --> hidePromoted
        featuresFolder --> hideRetweetBtn
        featuresFolder --> hideRetweets
        featuresFolder --> hideTrends
        featuresFolder --> imgAlt
        featuresFolder --> inlineCode
        featuresFolder --> inlineInsta
        featuresFolder --> kbShortcuts
        featuresFolder --> likesNav
        featuresFolder --> mentions
        featuresFolder --> preserveMsgs
        featuresFolder --> removeHeader
    end

    %% Storage
    storage["chrome.storage<br/>(local/sync)"]:::storage

    %% Test Harness
    subgraph "Test Harness (optional)"
        direction TB
        testRunner["test/index.js"]:::code
        fixture["test/fixtures/window.js"]:::code
        testRunner --> featuresFolder
        testRunner --> fixture
    end

    %% Click Events
    click webpack "https://github.com/sindresorhus/refined-twitter/blob/main/webpack.config.js"
    click manifest "https://github.com/sindresorhus/refined-twitter/blob/main/source/manifest.json"
    click background "https://github.com/sindresorhus/refined-twitter/blob/main/source/background.js"
    click content "https://github.com/sindresorhus/refined-twitter/blob/main/source/content.js"
    click featuresFolder "https://github.com/sindresorhus/refined-twitter/tree/main/source/features/"
    click autoLoad "https://github.com/sindresorhus/refined-twitter/blob/main/source/features/auto-load-new-tweets.js"
    click cleanNav "https://github.com/sindresorhus/refined-twitter/blob/main/source/features/clean-navbar-dropdown.js"
    click codeHighlight "https://github.com/sindresorhus/refined-twitter/blob/main/source/features/code-highlight.js"
    click disableColors "https://github.com/sindresorhus/refined-twitter/blob/main/source/features/disable-custom-colors.js"
    click hideFollow "https://github.com/sindresorhus/refined-twitter/blob/main/source/features/hide-follow-tweets.js"
    click hideMissed "https://github.com/sindresorhus/refined-twitter/blob/main/source/features/hide-in-case-you-missed-notifications.js"
    click hideLikeTweets "https://github.com/sindresorhus/refined-twitter/blob/main/source/features/hide-like-tweets.js"
    click hidePromoted "https://github.com/sindresorhus/refined-twitter/blob/main/source/features/hide-promoted-tweets.js"
    click hideRetweetBtn "https://github.com/sindresorhus/refined-twitter/blob/main/source/features/hide-retweet-buttons.js"
    click hideRetweets "https://github.com/sindresorhus/refined-twitter/blob/main/source/features/hide-retweets.js"
    click hideTrends "https://github.com/sindresorhus/refined-twitter/blob/main/source/features/hide-trends-and-who-to-follow.js"
    click imgAlt "https://github.com/sindresorhus/refined-twitter/blob/main/source/features/image-alternatives.js"
    click inlineCode "https://github.com/sindresorhus/refined-twitter/blob/main/source/features/inline-code.js"
    click inlineInsta "https://github.com/sindresorhus/refined-twitter/blob/main/source/features/inline-instagram-photos.js"
    click kbShortcuts "https://github.com/sindresorhus/refined-twitter/blob/main/source/features/keyboard-shortcuts.js"
    click likesNav "https://github.com/sindresorhus/refined-twitter/blob/main/source/features/likes-button-navbar.js"
    click mentions "https://github.com/sindresorhus/refined-twitter/blob/main/source/features/mentions-highlight.js"
    click preserveMsgs "https://github.com/sindresorhus/refined-twitter/blob/main/source/features/preserve-text-messages.js"
    click removeHeader "https://github.com/sindresorhus/refined-twitter/blob/main/source/features/remove-profile-header.js"
    click index "https://github.com/sindresorhus/refined-twitter/blob/main/source/features/index.js"
    click optionsPage "https://github.com/sindresorhus/refined-twitter/blob/main/source/options.html"
    click optionsPage "https://github.com/sindresorhus/refined-twitter/blob/main/source/options.js"
    click utils "https://github.com/sindresorhus/refined-twitter/blob/main/source/libs/utils.js"
    click storage "https://github.com/sindresorhus/refined-twitter/blob/main/source/style/content.css"
    click storage "https://github.com/sindresorhus/refined-twitter/blob/main/source/style/code-highlight.css"
    click testRunner "https://github.com/sindresorhus/refined-twitter/blob/main/test/index.js"
    click fixture "https://github.com/sindresorhus/refined-twitter/blob/main/test/fixtures/window.js"

    %% Styles
    classDef code fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef build fill:#EEEEEE,stroke:#999999,color:#333333;
    classDef ui fill:#DFFFE0,stroke:#228B22,color:#228B22;
    classDef storage fill:#FFF5BA,stroke:#DAA520,color:#DAA520;
```
