# ipfs/ipfs-companion architecture

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

- Interactive diagram: https://gitdiagram.com/ipfs/ipfs-companion
- Repository: https://github.com/ipfs/ipfs-companion

## Overview

##### Project type and purpose
- This is a browser extension (“IPFS Companion”) that integrates a locally‐running IPFS node into Chromium‐ and Firefox‐based browsers. It implements content scripts, background scripts, popup and options UIs, and landing‐page handlers to detect and redirect IPFS resources, bridge protocol handlers, and communicate with the IPFS API and gateway.

##### File‐structure analysis
- Top‐level build & config: `.babelrc`, `webpack.config.js`, `Dockerfile`, `Makefile`, CI workflows under `.github/workflows`, and `package.json`/`tsconfig.json`.
- `add-on/`: the entire WebExtension code. Inside it, subdirectories for:
- `_locales/` – translations
- `manifest.*.json` – browser‐specific manifests (MV2 & MV3)
- `src/background/` – background script entry point
- `src/contentScripts/` – content scripts injected into pages
- `src/lib/` – core logic modules (IPFS client, redirect‐handler, context menus, state, telemetry)
- `src/popup/` – browser action UI (HTML/CSS/JS)
- `src/options/` – options page UI and forms
- `src/landing-pages/` – built‐in permission and welcome pages
- `test/`: functional & e2e tests using Mocha, with mocks for WebExtension APIs.
- `docs/`: architecture notes, MV3 migration guide, release & localization docs.

##### README insights
- Describes the extension’s features: intercepting IPFS paths, DNSLink resolution, x-ipfs-path header handling, browser‐action menu, right‐click import, toggles.
- Mentions dependency on a local IPFS daemon (API & gateway), and optional public‐gateway fallbacks or external Web UI.

##### Main components & interactions
a. Components
- Browser Extension (WebExtension host)
- Background Script – central orchestrator, listens for WebRequest events, orchestrates redirects, talks to IPFS API, maintains state.
- Content Scripts – e.g., `linkifyDOM.js` for making plaintext links clickable, injected into web pages.
- Popup UI – the browser‐action menu (`popup/browser-action/...`) for user controls, status, import/pin actions.
- Options Page – React-style forms for preferences, gateway settings, experiments toggles.
- Landing Pages – built‐in HTML pages for permission requests, welcome screen.
- Lib Modules – shared business logic: IPFS client abstractions, redirect‐handlers, context‐menu builders, state management, telemetry.
- Manifest Files – configuration of permissions, background vs. content scripts, protocol handlers.
- External Services
- Local IPFS Daemon API (HTTP API, typically `localhost:5001`)
- Local IPFS Gateway (HTTP Gateway, typically `localhost:8080`)
- DNSLink DNS records lookup (via standard DNS and/or public gateways)
- Optional Public Gateways (for fallback) and IPFS Web UI dashboard
- Dev & CI Tooling
- Webpack/Babel build pipeline producing the extension bundle
- Mocha/E2E tests (via `test/e2e` and `test/functional`)
- Docker / docker‐compose for test environments
- Localization pipeline (`.tx`, `scripts/new-locale-key.sh`)

b. Relationships & data flows
- User clicks browser‐action → Popup UI sends message → Background Script queries `state` → optionally calls IPFS API or toggles redirect → responds to Popup.
- WebRequest event (page navigating to `/ipfs/{CID}`) → Background Script intercepts → checks with IPFS client lib → rewrites URL to gateway subdomain → browser reloads page at new URL.
- Content Script scans page DOM → finds plaintext IPFS links → posts message to Background Script → rewrites anchor `href` to `ipfs://` or redirect URL.
- Options Page reads/writes preferences → persists in browser storage via Background Script and lib/state.
- Telemetry events emitted from lib modules → sent to telemetry endpoint if enabled.
- DNSLink resolution chain: DNS lookup → determine IPNS record → redirect to `localhost:8080/ipns/...`.

c. Architectural patterns & design principles
- Modular “lib” layer for core logic, decoupled from UI and WebExtension APIs
- Event‐driven, message‐passing architecture (WebExtension messaging)
- Separation of concerns: background orchestrates, content scripts modify pages, UIs handle user interactions
- MV3‐compatible manifests with service worker vs. MV2 background scripts
- Feature toggles and experiments managed in a central state store

d. Key technologies & frameworks
- JavaScript/TypeScript, ES6+ transpiled by Babel
- Webpack for bundling
- Mocha + Chai for tests, Puppeteer/E2E harness
- WebExtension APIs (browser.*) for background, storage, runtime, webRequest
- Localization via Chrome‐style `_locales`
- Shell scripts and Node scripts in `scripts/` for asset generation and CI hooks

##### Final touches
- Lay out components logically: Extension on left, Local IPFS in center, External network on right.
- Important ports (`5001`, `8080`) and protocol handlers (`ipfs://`, `ipns://`).
- Manifest configuration as the “glue” that wires scripts to extension events.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser Extension Layer
    subgraph "Browser Extension" 
        direction TB
        BG["Background Script"]:::extComp
        CS["Content Script\n(linkifyDOM.js)"]:::extComp
        PU["Popup UI\n(browser-action)"]:::extComp
        QI["Quick-import Popup"]:::extComp
        OP["Options Page UI"]:::extComp
        LP["Landing Pages"]:::extComp
        LIB["Lib Modules"]:::extComp
        MAN["Manifest Files"]:::extComp
        ASSETS["_locales & Assets"]:::extComp
    end

    %% Local IPFS Services
    subgraph "Local IPFS Services"
        direction TB
        API["Local IPFS Daemon API\n(port 5001)"]:::local
        GW["Local IPFS Gateway\n(port 8080)"]:::local
    end

    %% External Network
    subgraph "External Network"
        direction TB
        DNS["DNSLink Resolver"]:::external
        PGW["Public Gateways"]:::external
        TEL["Telemetry Endpoint"]:::external
    end

    %% Dev & CI Tools
    subgraph "Dev & CI Tooling"
        direction TB
        BUILD["Webpack/Babel\nBundle"]:::dev
        TEST["Mocha/E2E & Functional Tests"]:::dev
        CI["CI Workflows"]:::dev
        SCRIPTS["Scripts"]:::dev
        DOCKER["Docker & Make"]:::dev
    end

    %% Relationships
    PU <-->|"message"| BG
    OP <-->|"message"| BG
    LP <-->|"navigation"| BG
    CS -->|"message"| BG
    BG -->|"HTTP API"| API
    BG -->|"Gateway Redirect"| GW
    DNS -->|"resolve IPNS"| BG
    BG -->|"DNSLink redirect"| GW
    LIB -->|"telemetry events"| TEL

    %% Build/Test pipelines
    BUILD -->|"produces"| BG
    TEST -->|"validates"| BG
    CI -->|"runs"| TEST
    CI -->|"runs"| BUILD
    SCRIPTS -->|"assist"| BUILD
    DOCKER -->|"env for"| TEST

    %% Click Events for component mapping
    click BG "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/background/background.js"
    click CS "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/contentScripts/linkifyDOM.js"
    click PU "https://github.com/ipfs/ipfs-companion/tree/main/add-on/src/popup/browser-action/"
    click QI "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/popup/quick-import.html"
    click QI "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/popup/quick-import.js"
    click QI "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/popup/quick-import.css"
    click ASSETS "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/popup/logo.js"
    click ASSETS "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/popup/heartbeat.css"
    click OP "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/options/options.html"
    click OP "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/options/options.js"
    click OP "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/options/options.css"
    click OP "https://github.com/ipfs/ipfs-companion/tree/main/add-on/src/options/forms/"
    click LP "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/landing-pages/permissions/request.html"
    click LP "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/landing-pages/permissions/request.js"
    click LP "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/landing-pages/permissions/request.css"
    click LP "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/landing-pages/welcome/index.html"
    click LP "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/landing-pages/welcome/index.js"
    click LP "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/landing-pages/welcome/page.js"
    click LP "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/landing-pages/welcome/store.js"
    click LIB "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/lib/ipfs-client/index.js"
    click LIB "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/lib/ipfs-client/brave.js"
    click LIB "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/lib/ipfs-client/external.js"
    click LIB "https://github.com/ipfs/ipfs-companion/tree/main/add-on/src/lib/redirect-handler/"
    click LIB "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/lib/state.js"
    click LIB "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/lib/telemetry.ts"
    click LIB "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/lib/context-menus/ContextMenus.ts"
    click LIB "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/lib/http-proxy.js"
    click LIB "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/lib/dnslink.js"
    click LIB "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/lib/ipfs-request.js"
    click LIB "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/lib/ipfs-path.js"
    click LIB "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/lib/notifier.js"
    click LIB "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/lib/on-installed.js"
    click LIB "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/lib/on-uninstalled.js"
    click LIB "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/lib/options.js"
    click LIB "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/lib/precache.js"
    click LIB "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/lib/copier.js"
    click LIB "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/lib/inspector.js"
    click LIB "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/lib/runtime-checks.js"
    click LIB "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/lib/ipfs-companion.js"
    click LIB "https://github.com/ipfs/ipfs-companion/blob/main/add-on/src/lib/ipfs-import.js"
    click MAN "https://github.com/ipfs/ipfs-companion/blob/main/add-on/manifest.common.json"
    click MAN "https://github.com/ipfs/ipfs-companion/blob/main/add-on/manifest.chromium.json"
    click MAN "https://github.com/ipfs/ipfs-companion/blob/main/add-on/manifest.firefox.json"
    click MAN "https://github.com/ipfs/ipfs-companion/blob/main/add-on/manifest.brave.json"
    click MAN "https://github.com/ipfs/ipfs-companion/blob/main/add-on/manifest.firefox-beta.json"
    click MAN "https://github.com/ipfs/ipfs-companion/blob/main/add-on/manifest.brave-beta.json"
    click ASSETS "https://github.com/ipfs/ipfs-companion/tree/main/add-on/_locales/"
    click ASSETS "https://github.com/ipfs/ipfs-companion/tree/main/add-on/icons/png/"
    click ASSETS "https://github.com/ipfs/ipfs-companion/tree/main/add-on/images/"
    click TEST "https://github.com/ipfs/ipfs-companion/blob/main/test/e2e/ipfs-companion.test.js"
    click TEST "https://github.com/ipfs/ipfs-companion/tree/main/test/functional/"
    click BUILD "https://github.com/ipfs/ipfs-companion/blob/main/.babelrc"
    click BUILD "https://github.com/ipfs/ipfs-companion/blob/main/webpack.config.js"
    click BUILD "https://github.com/ipfs/ipfs-companion/blob/main/tsconfig.json"
    click BUILD "https://github.com/ipfs/ipfs-companion/blob/main/package.json"
    click CI "https://github.com/ipfs/ipfs-companion/blob/main/.github/workflows/ci.yml"
    click CI "https://github.com/ipfs/ipfs-companion/blob/main/.github/workflows/e2e.yml"
    click CI "https://github.com/ipfs/ipfs-companion/blob/main/.github/workflows/generated-pr.yml"
    click CI "https://github.com/ipfs/ipfs-companion/blob/main/.github/workflows/stale.yml"
    click SCRIPTS "https://github.com/ipfs/ipfs-companion/tree/main/scripts/"
    click DOCKER "https://github.com/ipfs/ipfs-companion/tree/main/Dockerfile"
    click DOCKER "https://github.com/ipfs/ipfs-companion/blob/main/docker-compose.e2e.yml"
    click DOCKER "https://github.com/ipfs/ipfs-companion/tree/main/Makefile"

    %% Styles
    classDef extComp fill:#cce5ff,stroke:#2f6f9f,color:#000
    classDef local fill:#d4edda,stroke:#2f8f4f,color:#000
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#000
    classDef dev fill:#fff3cd,stroke:#d39e00,color:#000
```
