# briehq/brie-extension architecture

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

- Interactive diagram: https://gitdiagram.com/briehq/brie-extension
- Repository: https://github.com/briehq/brie-extension

## Overview

##### Project type and purpose
- This is a monorepo-driven Chrome Extension (“Brie”) built with Turborepo and pnpm.
- It captures screenshots, DOM events, console/Network errors, and user actions in real-time, storing them and surfacing them through various React-powered UIs (popup, in-page annotation overlay, and a runtime page).

##### File structure
- Top-level workflows and lint/build scripts under `.github/workflows`, `bash-scripts`, `husky`, etc.
- A `chrome-extension` folder with `manifest.ts`, background code, plugins, and build config.
- A `packages` workspace containing reusable libraries:
- `shared` (constants, interfaces, utils, HOCs)
- `ui` (design system, Tailwind config, React primitives)
- `store` (state management, API services, Redux slices)
- `storage` (Chrome storage adapters)
- `i18n` (localization engine)
- `env`, `dev-utils`, `hmr`, `tailwindcss-config`, `vite-config`, `zipper`.
- Three “pages” apps under `/pages`:
- `content-runtime` – embedded React runtime page
- `content-ui` – in-page overlay/annotation UI
- E2E tests under `tests/e2e` for each page.

##### Key README insights
- Core use case: “Capture & Share Instantly” for bug reporting.
- Tech stack: React, Vite, Turborepo, Chrome Extension API.

A. Browser Extension Host
- Manifest
- Background script (singleton event/message router)
- Content Script + Injected Scripts (DOM/event interceptors, network/console interceptors)
B. Client UIs (all React + Vite)
- Popup UI (`pages/popup`)
- In-page Annotation UI (`pages/content-ui`)
- Runtime Page UI (`pages/content-runtime`)
C. Monorepo Packages (compiled & bundled into the above)
1. shared – types, constants, utils, HOCs
2. ui – design system components + Tailwind config
3. store – Redux slices + API services + React hooks
4. storage – Chrome storage layer for persisting history, tokens, theming, etc.
5. i18n – locale loaders & codegen for multi-language support
6. build tools – env, dev-utils, hmr, vite-config, zipper, tailwindcss-config
D. External Services
- Brie backend API (for submitting/syncing bug reports)
- OAuth / Identity provider (for user authentication)

##### Relationships and data flow
- User action in browser → Content Script / Injected Scripts capture event → sendMessage → Background
- Background → persists data with `storage` package (Chrome.storage)
- UIs (Popup or In-page) → dispatch Redux actions via `store` → may fetch remote data via API services
- Shared UI components & i18n used across all pages
- Build time: `vite-config`, `hmr`, `dev-utils`, `zipper` produce individual bundles for each page + extension bundle

##### Architectural patterns & principles
- Monorepo with reusable, versioned packages → enforce DRY and consistency
- Clear separation of concerns:
- Content layer (data capture)
- Background layer (coordination & persistence)
- Presentation layer (React UIs)
- Pub/Sub via Chrome messaging for loose coupling
- State management with Redux slices exposed via React hooks
- Build‐time code generation and HMR for rapid iteration

##### Detailed checklist
[ ] Browser Extension Host
– manifest.json → background.js
– background ↔ contentScript / injectedScript messaging
– background → chrome.storage (via `storage` lib)
[ ] React UIs (Popup, Content UI, Runtime UI)
– load via extension (popup.html) or injected DOM
– connect to store (Redux + hooks) and background messaging
– render via `ui` & `shared` components; localize via `i18n`
[ ] Packages & Build Tooling
– show `hmr`, `vite-config`, `dev-utils`, `zipper`, `tailwindcss-config` feeding into each page’s build
[ ] External Services
– Brie API endpoint for report submission
– Identity provider / OAuth flows

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Browser Extension Host"
        Manifest["Manifest"]:::extension
        Background["Background Script"]:::extension
        subgraph "Content Components"
            ContentScript["Content Script"]:::extension
            Injected["Injected Scripts"]:::extension
            NetworkI["Network Interceptors"]:::extension
            ConsoleI["Console Interceptors"]:::extension
            AppStorageI["Application Storage Interceptors"]:::extension
            EventI["Event Interceptors"]:::extension
        end
        StorageAPI["Chrome.storage"]:::extension
    end

    subgraph "React UIs"
        Popup["Popup UI"]:::ui
        ContentUI["Content Annotation UI"]:::ui
        RuntimeUI["Runtime Page UI"]:::ui
    end

    subgraph "Build & Shared Libs"
        Shared["Shared (types, utils, HOCs)"]:::libs
        UIlib["UI Library"]:::libs
        TailwindCfg["Tailwind Config"]:::libs
        Store["Store (Redux, API)"]:::libs
        StorageLib["Storage Adapters"]:::libs
        I18n["Localization Engine"]:::libs
        Env["Env Tooling"]:::libs
        DevUtils["Dev Utilities"]:::libs
        HMR["HMR Tooling"]:::libs
        ViteCfg["Vite Config"]:::libs
        Zipper["ZIP Packaging"]:::libs
    end

    subgraph "External Services"
        BrieAPI["Brie Backend API"]:::external
        OAuth["OAuth / Identity"]:::external
    end

    %% Runtime interactions
    ContentScript -->|sendMessage| Background
    Injected -->|sendMessage| Background
    Background -->|persist| StorageAPI
    Popup -->|query & dispatch| Background
    ContentUI -->|query & dispatch| Background
    RuntimeUI -->|query & dispatch| Background
    Popup -->|submit report| BrieAPI
    ContentUI -->|submit report| BrieAPI
    RuntimeUI -->|authenticate| OAuth

    %% Build-time dependencies (dashed)
    Shared -.-> Manifest
    Shared -.-> Background
    Shared -.-> ContentScript
    Shared -.-> Popup
    Shared -.-> ContentUI
    Shared -.-> RuntimeUI

    UIlib -.-> Popup
    UIlib -.-> ContentUI
    UIlib -.-> RuntimeUI

    TailwindCfg -.-> Popup
    TailwindCfg -.-> ContentUI
    TailwindCfg -.-> RuntimeUI

    Store -.-> Popup
    Store -.-> ContentUI
    Store -.-> RuntimeUI

    StorageLib -.-> Background
    StorageLib -.-> RuntimeUI

    I18n -.-> Popup
    I18n -.-> ContentUI
    I18n -.-> RuntimeUI

    Env -.-> Manifest
    DevUtils -.-> Manifest
    HMR -.-> Popup
    HMR -.-> ContentUI
    HMR -.-> RuntimeUI
    ViteCfg -.-> Popup
    ViteCfg -.-> ContentUI
    ViteCfg -.-> RuntimeUI
    Zipper -.-> Manifest
    Zipper -.-> Popup
    Zipper -.-> ContentUI
    Zipper -.-> RuntimeUI

    %% Click events
    click Manifest "https://github.com/briehq/brie-extension/blob/main/chrome-extension/manifest.ts"
    click Background "https://github.com/briehq/brie-extension/blob/main/chrome-extension/src/background/index.ts"
    click ContentScript "https://github.com/briehq/brie-extension/blob/main/pages/content/src/index.ts"
    click Injected "https://github.com/briehq/brie-extension/blob/main/pages/content/src/injected-scripts/index.ts"
    click NetworkI "https://github.com/briehq/brie-extension/tree/main/pages/content/src/interceptors/network"
    click ConsoleI "https://github.com/briehq/brie-extension/tree/main/pages/content/src/interceptors/console"
    click AppStorageI "https://github.com/briehq/brie-extension/tree/main/pages/content/src/interceptors/application"
    click EventI "https://github.com/briehq/brie-extension/tree/main/pages/content/src/interceptors/events"
    click Popup "https://github.com/briehq/brie-extension/tree/main/pages/popup/src"
    click ContentUI "https://github.com/briehq/brie-extension/tree/main/pages/content-ui/src"
    click RuntimeUI "https://github.com/briehq/brie-extension/tree/main/pages/content-runtime/src"
    click Shared "https://github.com/briehq/brie-extension/tree/main/packages/shared"
    click UIlib "https://github.com/briehq/brie-extension/tree/main/packages/ui"
    click TailwindCfg "https://github.com/briehq/brie-extension/tree/main/packages/tailwindcss-config"
    click Store "https://github.com/briehq/brie-extension/tree/main/packages/store"
    click StorageLib "https://github.com/briehq/brie-extension/tree/main/packages/storage"
    click I18n "https://github.com/briehq/brie-extension/tree/main/packages/i18n"
    click Env "https://github.com/briehq/brie-extension/tree/main/packages/env"
    click DevUtils "https://github.com/briehq/brie-extension/tree/main/packages/dev-utils"
    click HMR "https://github.com/briehq/brie-extension/tree/main/packages/hmr"
    click ViteCfg "https://github.com/briehq/brie-extension/tree/main/packages/vite-config"
    click Zipper "https://github.com/briehq/brie-extension/tree/main/packages/zipper"

    %% Styles
    classDef extension fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef ui fill:#c8e6c9,stroke:#388e3c,color:#1b5e20
    classDef libs fill:#eceff1,stroke:#90a4ae,color:#37474f
    classDef external fill:#ffe0b2,stroke:#f57c00,color:#e65100
```
