# martinjaskulla/cc_extension architecture

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

- Interactive diagram: https://gitdiagram.com/martinjaskulla/cc_extension
- Repository: https://github.com/martinjaskulla/cc_extension

## Overview

##### Project type and purpose
- This is a browser extension (specifically a Chrome/Chromium extension) built with TypeScript.
- It provides a background script that likely intercepts or rewrites network requests, plus custom DevTools pages/panes to inspect or control that behavior at runtime.
- Key use case: override or proxy loaded JavaScript files (e.g., “test-file-to-overwrite/main-123.js”) via a local HTTP server and observe/debug the effect through DevTools.

##### File structure
- entrypoints/
- background.ts      → background script, loaded persistently by the extension
- devtools/          → a standalone DevTools page (e.g., a sidebar or full-page extension)
- devtools-panel/    → custom DevTools Panel (under the “Sources” or “Network” tab)
- devtools-pane/     → custom DevTools sidebar/pane in the Elements or Sources panel
- public/
- replacement.js     → content-script or web-accessible resource used to overwrite or inject code
- assets/               → static assets (images, fonts)
- package.json, tsconfig.json, wxt.config.ts
- build tooling and manifest generation

##### README for additional insights
- Instructions to debug background.ts via chrome://extensions
- Steps to host a test file on localhost:2999 (via http-server)
- Example fetch against localhost URL to trigger the extension’s interception logic

##### Main components and interactions
a. Components
1. Chrome Browser (host environment)
2. Extension Background Script (background.ts)
3. DevTools UI
– DevTools Page (entrypoints/devtools)
– DevTools Panel (entrypoints/devtools-panel)
– DevTools Sidebar/Pane (entrypoints/devtools-pane)
4. Content Script / Web-Accessible Script (public/replacement.js)
5. External HTTP Server (localhost:2999, serves test-file-to-overwrite)
6. Web Page under test (the target page where fetch('…/main-123.js') is called)

b. Relationships & data flow
– The Web Page issues a fetch() for main-123.js
– Chrome’s networking layer triggers the Background Script’s webRequest listener
- Background Script may redirect or rewrite the request to localhost:2999/main-123.js
– The External HTTP Server returns the test file
– The Web Page loads the overridden script
– DevTools UI components communicate with the Background Script via chrome.devtools.* APIs
- The DevTools Panel and Pane request status/logs from the Background Script
- The DevTools Page may offer custom controls or visualizations
– (Optional) Content Script replacement.js can be injected into the Web Page to modify DOM or observe runtime behavior

c. Architectural patterns / design principles
– Event-driven messaging (chrome.runtime.sendMessage / onMessage)
– Separation of concerns:
- Background script handles networking and state
- DevTools UI handles presentation and user input
- Content script (if used) handles in-page logic
– Modular entrypoints: each DevTools component lives in its own folder with its HTML + main.ts

d. Key technologies / frameworks
– TypeScript
– Chrome Extension APIs (chrome.runtime, chrome.devtools, chrome.webRequest)
– “wxt.config.ts” suggests Web Extension Toolkit (for bundling/manifest)
– http-server (for local test hosting)
– Vite or similar bundler (implied by tsconfig, and possibly wxt)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Extension inside Chrome Browser
    subgraph "Chrome Browser"
        subgraph "Extension Package"
            BG["Background Script<br>(background.ts)"]:::internal
            DTPage["DevTools Page<br>(index.html & main.ts)"]:::internal
            DTPanel["DevTools Panel<br>(index.html & main.ts)"]:::internal
            DTPane["DevTools Pane<br>(index.html & main.ts)"]:::internal
            Content["Replacement Script<br>(replacement.js)"]:::internal
            Assets["Static Assets<br>(assets/)"]:::internal
            Icons["Icons<br>(public/icon/)"]:::internal
            Config["Build & Manifest<br>(wxt.config.ts, tsconfig.json,<br>package.json)"]:::internal
        end
    end

    %% External systems
    WebPage["Web Page<br>(fetch main-123.js)"]:::external
    Server["External HTTP Server<br>(localhost:2999)"]:::external

    %% Data flows and interactions
    WebPage -->|"webRequest event"| BG
    BG -->|"redirect to localhost:2999"| Server
    Server -->|"serves test script"| WebPage

    DTPage <-->|"chrome.runtime messaging"| BG
    DTPanel <-->|"chrome.runtime messaging"| BG
    DTPane <-->|"chrome.runtime messaging"| BG

    Content -.->|"injected via manifest"| WebPage

    %% Click Events
    click BG "https://github.com/martinjaskulla/cc_extension/blob/main/entrypoints/background.ts"
    click DTPage "https://github.com/martinjaskulla/cc_extension/blob/main/entrypoints/devtools/index.html"
    click DTPage "https://github.com/martinjaskulla/cc_extension/blob/main/entrypoints/devtools/main.ts"
    click DTPanel "https://github.com/martinjaskulla/cc_extension/blob/main/entrypoints/devtools-panel/index.html"
    click DTPanel "https://github.com/martinjaskulla/cc_extension/blob/main/entrypoints/devtools-panel/main.ts"
    click DTPane "https://github.com/martinjaskulla/cc_extension/blob/main/entrypoints/devtools-pane/index.html"
    click DTPane "https://github.com/martinjaskulla/cc_extension/blob/main/entrypoints/devtools-pane/main.ts"
    click Content "https://github.com/martinjaskulla/cc_extension/blob/main/public/replacement.js"
    click Assets "https://github.com/martinjaskulla/cc_extension/tree/main/assets/"
    click Icons "https://github.com/martinjaskulla/cc_extension/tree/main/public/icon/"
    click Config "https://github.com/martinjaskulla/cc_extension/blob/main/wxt.config.ts"

    %% Styles
    classDef internal fill:#D0E8FF,stroke:#0366d6,color:#000
    classDef external fill:#D8F5A2,stroke:#228B22,color:#000
    classDef optional stroke-dasharray: 5 5,color:#900
```
