# withgraphite/graphite-chrome-extension architecture

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

- Interactive diagram: https://gitdiagram.com/withgraphite/graphite-chrome-extension
- Repository: https://github.com/withgraphite/graphite-chrome-extension

## Overview

##### File structure
- Top-level config: .eslintrc, tsconfig.json, Yarn v3, esbuild script
- public/manifest.json – Chrome extension manifest and static assets
- src/background.ts – long-running background script handling API communication, authentication, storage
- src/pr-content-script.ts – content script injected into GitHub PR pages to render overlays and capture DOM events
- scripts/esbuild.js – custom build pipeline for bundling TS to browser-compatible JS

##### README for additional insights
- Confirms this is a closed-beta code review tool
- Mentions syncing changes and reviews via Graphite’s API (so the extension must authenticate and relay pull request data)

##### Main components
a. Browser & Extension Host
- Content Script (pr-content-script.ts)
- Background Script (background.ts)
- Browser Storage (LocalStorage or Extension storage)
b. GitHub Pull Request Page (DOM target for content script)
c. Graphite Backend API (external service)
d. Build Pipeline (esbuild script, Yarn)

##### Relationships and interactions
- Content Script ↔ Background Script via Chrome Runtime Messaging
- Content Script reads/writes to the GitHub PR DOM, captures review events (clicks, comments)
- Background Script handles authentication tokens, caches data in extension storage, and makes HTTP/HTTPS calls to Graphite API
- Graphite Backend responds with review threads, code snippets, and syncs PR state
- Build Pipeline (esbuild) processes src/*.ts → public/*.js and packages manifest

##### Architectural patterns & design principles
- Event-driven message passing between content and background scripts
- Single responsibility: content script for UI injection, background for networking and storage
- Separation of concerns via manifest declaring permissions and script roles

##### Technologies & frameworks
- TypeScript (strict typing)
- esbuild (fast, JS bundler)
- Yarn v3 (package management, PnP)
- Chrome Extension APIs (runtime messaging, storage, contentScripts)

##### Detail
- Manifest’s role in declaring permissions (e.g., host permissions for api.graphite.dev, content_scripts targeting github.com)
- Build script outside of the browser boundary, feeding into the extension package

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Browser Environment
    subgraph "Browser Environment"
        subgraph "Extension Host"
            ContentScript["Content Script"]:::internal
            BackgroundScript["Background Script"]:::internal
            Storage[(Browser Storage)]:::storage
            Manifest["Manifest & Static Assets"]:::internal
        end
        GitHubDOM["GitHub PR Page (DOM)"]:::external
    end

    %% External Service
    GraphiteAPI["Graphite Backend API"]:::external

    %% Build and Config
    subgraph "Config & Build Tools"
        PackageJson["package.json"]:::build
        Tsconfig["tsconfig.json"]:::build
        Eslint[".eslintrc"]:::build
        Yarn[".yarn/"]:::build
        Esbuild["Build Pipeline (esbuild)"]:::build
    end

    %% Relationships
    ContentScript -->|"chrome.runtime.sendMessage"| BackgroundScript
    BackgroundScript -->|"chrome.storage.local.set/get"| Storage
    ContentScript <-->|"DOM queries & events"| GitHubDOM
    BackgroundScript -->|"fetch POST/GET"| GraphiteAPI
    Esbuild -->|"bundles & packages"| ContentScript
    Esbuild -->|"bundles & packages"| BackgroundScript
    Esbuild -->|"includes manifest & assets"| Manifest
    PackageJson --> Esbuild
    Tsconfig --> Esbuild
    Eslint --> Esbuild
    Yarn --> Esbuild

    %% Click Events
    click ContentScript "https://github.com/withgraphite/graphite-chrome-extension/blob/main/src/pr-content-script.ts"
    click BackgroundScript "https://github.com/withgraphite/graphite-chrome-extension/blob/main/src/background.ts"
    click Manifest "https://github.com/withgraphite/graphite-chrome-extension/blob/main/public/manifest.json"
    click Esbuild "https://github.com/withgraphite/graphite-chrome-extension/blob/main/scripts/esbuild.js"
    click Tsconfig "https://github.com/withgraphite/graphite-chrome-extension/blob/main/tsconfig.json"
    click Eslint "https://github.com/withgraphite/graphite-chrome-extension/blob/main/.eslintrc"
    click Yarn "https://github.com/withgraphite/graphite-chrome-extension/tree/main/.yarn/"
    click PackageJson "https://github.com/withgraphite/graphite-chrome-extension/blob/main/package.json"

    %% Styles
    classDef internal fill:#D0E8FF,stroke:#000,stroke-width:1px
    classDef external fill:#D5E8D4,stroke:#000,stroke-width:1px
    classDef build fill:#FFF2CC,stroke:#000,stroke-width:1px
    classDef storage fill:#FFE599,stroke:#000,stroke-width:1px
```
