# googlechromelabs/ps-analysis-tool architecture

> Architecture diagram of the GitHub repository googlechromelabs/ps-analysis-tool, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/googlechromelabs/ps-analysis-tool
- Repository: https://github.com/googlechromelabs/ps-analysis-tool

## Overview

##### Main Components and Their Roles
- Chrome Extension & DevTools Integration: The core of the project is the “extension” package. This contains content scripts, service workers, popovers, and integration with Chrome DevTools. Indicate how it interacts with the browser (e.g., capturing network events, intercepting cookie data, and injecting UI components).
- Command Line Interfaces and Dashboards: There are packages such as “cli”, “cli-dashboard”, and “report” that provide command-line tooling and dashboard interfaces for analysis and reporting.
- Shared Libraries and Utilities: Several packages (like “analysis-utils”, “common”, and “library-detection”) offer loosely coupled business logic, type definitions, and helper functions used across the extension, CLI, and reporting modules.
- UI Component Library: The “design-system” package encapsulates the reusable React components (buttons, tables, dialogs, and other widgets) that form the user interfaces for the extension’s DevTools views as well as the CLI dashboards.
- Internationalization (i18n): The “i18n” package manages the translations and locale-specific messages.
- Additional Tools: Packages such as “explorable-explanations” provide interactive components or guided explanations about the Privacy Sandbox APIs, possibly used in learning and helping end users understand the privacy transition.

##### Relationships and Interactions
- The Extension Package interacts with Chrome:
- Content Scripts observe and process pages.
- Service Workers and background listeners provide event-driven capabilities (e.g., intercepting network requests, handling cookie transformations).
- The Extension’s “store” modules and utility functions (such as those in “analysis-utils” and “common”) persist state and manage data flow.
- The CLI and Dashboard components are used for offline analysis and generating reports based on the same underlying logic as the extension. Show that these components consume shared libraries.
- The “library-detection” package scans for and reports on third-party dependencies (like Disqus, Facebook Comments, etc.), which are then utilized by both the extension and report modules.

##### Important Architectural Patterns
- Modular Monorepo Architecture: Emphasize that the codebase is split into many self-contained packages that interact via well-defined interfaces. This separation supports clear dependency injection and testing.
- Separation of Concerns: For instance, the UI, business logic, data transformation (cookie analysis), and technical integration with Chrome are all separated into different packages.
- Client-side Focus with Extensive Use of Web Technologies: Since this project is aimed at Chrome DevTools integration, the architecture is predominantly client and browser based, leveraging React, TypeScript, and modern build tools (Babel, Webpack).

##### Additional Elements
- Annotations or legends to explain:
– Which parts are executed in the browser (extension, content scripts, service worker).
– Which parts are standalone tools (CLI, dashboard, report generation).
– How state management and data flow occur (using the “store” modules in extension and state providers in the UI layers).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Integration
    CB["Chrome Browser"]:::external

    %% Chrome Extension & DevTools Integration
    subgraph "Chrome Extension & DevTools Integration"
        ext["Extension Package"]:::extStyle
        cs["Content Scripts"]:::extStyle
        sw["Service Workers"]:::extStyle
        uiExt["DevTools UI"]:::extStyle
    end

    %% CLI & Dashboard Tools
    subgraph "CLI & Dashboard Tools"
        cli["CLI"]:::cliStyle
        cliDash["CLI Dashboard"]:::cliStyle
        report["Report & Dashboard"]:::cliStyle
    end

    %% Shared Libraries & Utilities
    subgraph "Shared Libraries & Utilities"
        analysis["Analysis Utils"]:::utilStyle
        common["Common Utilities"]:::utilStyle
        libDetect["Library Detection"]:::utilStyle
    end

    %% UI Components & Internationalization
    subgraph "UI Components & Internationalization"
        design["Design System"]:::uiStyle
        intl["Internationalization (i18n)"]:::uiStyle
    end

    %% Additional Tools
    subgraph "Additional Tools"
        expl["Explorable Explanations"]:::toolStyle
    end

    %% Auxiliary: CI/CD & Testing
    ci["CI/CD & Testing (GitHub Workflows)"]:::note

    %% Connections: External Browser to Extension
    CB -->|"interacts"| ext

    %% Internal connections within Extension Package
    ext -->|"includes"| cs
    ext -->|"includes"| sw
    ext -->|"includes"| uiExt

    %% Extension Package dependencies
    ext -->|"uses"| analysis
    ext -->|"uses"| common
    ext -->|"uses"| libDetect
    ext -->|"leverages"| design
    ext -->|"utilizes"| intl

    %% CLI & Dashboard dependencies
    cli -->|"uses"| analysis
    cli -->|"uses"| common
    cli -->|"utilizes"| intl

    cliDash -->|"uses"| design
    cliDash -->|"uses"| analysis
    cliDash -->|"uses"| common

    report -->|"integrates"| libDetect
    report -->|"uses"| design
    report -->|"uses"| common
    report -->|"uses"| analysis
    report -->|"utilizes"| intl

    %% Additional Tools support
    expl -->|"augments"| ext

    %% CI/CD & Testing supports all major modules
    ci --- ext
    ci --- cli
    ci --- report
    ci --- analysis
    ci --- design

    %% Click Events
    click ext "https://github.com/googlechromelabs/ps-analysis-tool/tree/main/packages/extension"
    click cli "https://github.com/googlechromelabs/ps-analysis-tool/tree/main/packages/cli"
    click cliDash "https://github.com/googlechromelabs/ps-analysis-tool/tree/main/packages/cli-dashboard"
    click report "https://github.com/googlechromelabs/ps-analysis-tool/tree/main/packages/report"
    click analysis "https://github.com/googlechromelabs/ps-analysis-tool/tree/main/packages/analysis-utils"
    click common "https://github.com/googlechromelabs/ps-analysis-tool/tree/main/packages/common"
    click libDetect "https://github.com/googlechromelabs/ps-analysis-tool/tree/main/packages/library-detection"
    click design "https://github.com/googlechromelabs/ps-analysis-tool/tree/main/packages/design-system"
    click intl "https://github.com/googlechromelabs/ps-analysis-tool/tree/main/packages/i18n"
    click expl "https://github.com/googlechromelabs/ps-analysis-tool/tree/main/packages/explorable-explanations"

    %% Styles
    classDef extStyle fill:#f9f,stroke:#333,stroke-width:2px;
    classDef cliStyle fill:#9f9,stroke:#333,stroke-width:2px;
    classDef utilStyle fill:#ff9,stroke:#333,stroke-width:2px;
    classDef uiStyle fill:#9ff,stroke:#333,stroke-width:2px;
    classDef toolStyle fill:#fc9,stroke:#333,stroke-width:2px;
    classDef external fill:#ddd,stroke:#333,stroke-width:2px,font-style:italic;
    classDef note fill:#eee,stroke:#888,stroke-dasharray:5 5,stroke-width:2px;
```
