# pnd280/complexity architecture

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

- Interactive diagram: https://gitdiagram.com/pnd280/complexity
- Repository: https://github.com/pnd280/complexity

## Overview

##### Project Type and Purpose
- This is a monorepo (pnpm + Turbo) containing:
– Reusable packages (async-dep-manager, cli-logger, eslint-config, i18n, typescript-config, webext-bridge)
– A browser-extension (“perplexity/extension”) built in TypeScript + React + Vite targeting Perplexity AI (Chrome/Firefox)
- Purpose: deliver a highly modular, customizable suite of UI/UX enhancements—via a plugin system—for AI chat web apps

##### File-Structure Analysis
- Top level: monorepo config (.gitignore, pnpm-workspace.yaml, turbo.json, Husky, VSCode, ESLint, TypeScript)
- packages/: small libraries providing core capabilities (async-registry, CLI logger, i18n support, shared configs)
- perplexity/extension/: the extension’s source—entrypoints (background, content-scripts, options page), React components, services, plugin modules, tests, CLI, docs, build (Vite, gulp)

##### Key README Insights
- “Complexity” is now a suite, originally a Perplexity AI extension—focus on modular enhancements
- Invites you to “./perplexity/extension/” for architecture details

a. Monorepo Packages Layer
– Shared packages: async-dep-manager, cli-logger, eslint-config, i18n, typescript-config
– pnpm + Turbo orchestrates build & dependency graph
b. Extension Runtime Layer
1. Manifest (chrome/firefox)
2. Entry Points
– background.ts: central hub—handles permissions, network proxy, message routing
– content-scripts: inject into pages—DOM observers, main-world integration
– options-page (React): UI for plugin configuration & dashboard
3. Services
– extension-permissions, extension-settings, instant-css, indexed-db, pplx-api, cplx-api, i18n
4. Plugin System
– plugin registry (core async-dep, cache, hooks)
– Multiple plugin modules under src/plugins/**
5. UI Components
– core UI (Toaster, Tooltip, Buttons…)
– domain UI (dashboard pages, plugin UIs)
c. Build & Delivery Layer
– CLI under perplexity/extension/cli for versioning, publishing to Chrome/AMO
– Vite + gulp build pipelines produce manifest-ready bundles
– E2E (Playwright), unit tests (Vitest)

##### Architectural Patterns & Principles
- Monorepo with well-defined package boundaries for reuse
- Plugin architecture: lazy-loaded plugins, async dependency registry, isolation via content scripts vs. main-world injection
- Separation of concerns:
– “Services” layer abstracts storage, network, permissions
– “UI” layer purely React + state via TanStack Query + Zustand
– “Entry points” layer wires environment specifics

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Monorepo & Build Layer
    subgraph "Monorepo & Build" 
        direction TB
        PNPM["pnpm + Turbo"]:::orchestrator
        subgraph "Packages" 
            direction TB
            ADM["async-dep-manager"]:::pkg
            CLG["cli-logger"]:::pkg
            ESL["eslint-config"]:::pkg
            I18N_CFG["i18n"]:::pkg
            TS_CFG["typescript-config"]:::pkg
            WEBBR["webext-bridge"]:::pkg
        end
        subgraph "Build & Delivery Tools"
            direction TB
            CLI_TOOL["Extension CLI"]:::build
            VITE_CFG["Vite Config & Plugins"]:::build
            GULP["Gulp Build Tasks"]:::build
            E2E["E2E Tests (Playwright)"]:::build
            UNIT["Unit Tests (Vitest)"]:::build
        end
    end

    %% Extension Host Layer
    subgraph "Extension Host" 
        direction TB
        MANIFEST_BASE["manifest.base.ts"]:::manifest
        MANIFEST_CHR["manifest.chrome.ts"]:::manifest
        MANIFEST_FF["manifest.firefox.ts"]:::manifest

        BG["background.ts"]:::background
        CS["content-scripts"]:::contentscript
        OPT["options-page"]:::options

    end

    %% Services & Data Layer
    subgraph "Services & Data"
        direction TB
        PERM["extension-permissions"]:::service
        SETT["extension-settings"]:::service
        CSS["instant-css"]:::service
        IDXDB["indexed-db"]:::db
        PPLX["pplx-api"]:::api
        CPLX["cplx-api"]:::api
        LOC["i18n"]:::service
        PLG_ST["plugins-states"]:::service

        REG_DATA["plugin-registry (data)"]:::service
    end

    %% UI & Plugins Layer
    subgraph "UI & Plugins"
        direction TB
        subgraph "Core UI Components"
            direction TB
            UI_SHARED["components (Toaster, Tooltip, Buttons)"]:::ui
        end
        subgraph "Plugin Core Infrastructure"
            direction TB
            PLG_REG["async-dep-registry"]:::plugin
            PLG_CACHE["core cache loaders"]:::plugin
            PLG_DOM["core dom-observers"]:::plugin
            PLG_MW["core main-world bridge"]:::plugin
            PLG_UIROOT["core UI root & groups"]:::plugin
        end
        subgraph "Options Page UI"
            direction TB
            SIDEBAR["sidebar & shell"]:::ui
            DASH_PLUG["dashboard plugins UI"]:::ui
            THEMES["themes & settings pages"]:::ui
            ONBOARD["onboarding flows"]:::ui
        end
    end

    %% Connections
    PNPM -->|orchestrates build| ADM
    PNPM --> CLG
    PNPM --> ESL
    PNPM --> I18N_CFG
    PNPM --> TS_CFG
    PNPM --> WEBBR
    PNPM --> CLI_TOOL
    PNPM --> VITE_CFG
    PNPM --> GULP
    PNPM --> E2E
    PNPM --> UNIT

    CLI_TOOL -->|builds extension| BG
    VITE_CFG --> BG
    GULP --> BG

    BG <-->|message passing| CS
    BG -->|routes messages| PERM
    BG -->|routes messages| REG_DATA

    CS -->|injects UI| UI_SHARED
    CS -->|calls| PERM

    OPT -->|UI bootstraps| SIDEBAR
    OPT -->|UI bootstraps| DASH_PLUG
    OPT -->|UI bootstraps| THEMES
    OPT -->|UI bootstraps| ONBOARD

    SIDEBAR -->|read/write| SETT
    DASH_PLUG -->|calls| REG_DATA
    THEMES -->|calls| SETT
    ONBOARD -->|calls| SETT

    UI_SHARED -->|calls| PPLX
    UI_SHARED -->|calls| CPLX
    UI_SHARED -->|uses| LOC

    PERM -->|stores| IDXDB
    SETT -->|stores| IDXDB
    CSS -->|injects styles| CS
    PLG_ST -->|tracks| REG_DATA

    PLG_REG --> REG_DATA
    PLG_CACHE --> REG_DATA
    PLG_DOM --> REG_DATA
    PLG_MW --> REG_DATA
    PLG_UIROOT --> REG_DATA

    %% Click Events - Monorepo Packages
    click ADM "https://github.com/pnd280/complexity/tree/nxt/packages/async-dep-manager"
    click CLG "https://github.com/pnd280/complexity/tree/nxt/packages/cli-logger"
    click ESL "https://github.com/pnd280/complexity/tree/nxt/packages/eslint-config"
    click I18N_CFG "https://github.com/pnd280/complexity/tree/nxt/packages/i18n"
    click TS_CFG "https://github.com/pnd280/complexity/tree/nxt/packages/typescript-config"
    click WEBBR "https://github.com/pnd280/complexity/tree/nxt/packages/webext-bridge"

    %% Click Events - Manifests
    click MANIFEST_BASE "https://github.com/pnd280/complexity/blob/nxt/perplexity/extension/src/manifest.base.ts"
    click MANIFEST_CHR "https://github.com/pnd280/complexity/blob/nxt/perplexity/extension/src/manifest.chrome.ts"
    click MANIFEST_FF "https://github.com/pnd280/complexity/blob/nxt/perplexity/extension/src/manifest.firefox.ts"

    %% Click Events - Entry Points
    click BG "https://github.com/pnd280/complexity/blob/nxt/perplexity/extension/src/entrypoints/background/index.ts"
    click CS "https://github.com/pnd280/complexity/blob/nxt/perplexity/extension/src/entrypoints/content-scripts/index.ts"
    click OPT "https://github.com/pnd280/complexity/blob/nxt/perplexity/extension/src/entrypoints/options-page/index.tsx"

    %% Click Events - Services
    click PERM "https://github.com/pnd280/complexity/tree/nxt/perplexity/extension/src/services/extension-permissions"
    click SETT "https://github.com/pnd280/complexity/tree/nxt/perplexity/extension/src/services/extension-settings"
    click CSS "https://github.com/pnd280/complexity/tree/nxt/perplexity/extension/src/services/instant-css"
    click IDXDB "https://github.com/pnd280/complexity/tree/nxt/perplexity/extension/src/services/indexed-db"
    click PPLX "https://github.com/pnd280/complexity/tree/nxt/perplexity/extension/src/services/pplx-api"
    click CPLX "https://github.com/pnd280/complexity/tree/nxt/perplexity/extension/src/services/cplx-api"
    click LOC "https://github.com/pnd280/complexity/tree/nxt/perplexity/extension/src/services/i18n"
    click PLG_ST "https://github.com/pnd280/complexity/tree/nxt/perplexity/extension/src/services/plugins-states"

    %% Click Events - Plugin Core
    click REG_DATA "https://github.com/pnd280/complexity/tree/nxt/perplexity/extension/src/data/plugin-registry"
    click PLG_REG "https://github.com/pnd280/complexity/blob/nxt/perplexity/extension/src/plugins/_core/async-dep-registry.ts"
    click PLG_CACHE "https://github.com/pnd280/complexity/tree/nxt/perplexity/extension/src/plugins/_core/cache"
    click PLG_DOM "https://github.com/pnd280/complexity/tree/nxt/perplexity/extension/src/plugins/_core/dom-observers"
    click PLG_MW "https://github.com/pnd280/complexity/tree/nxt/perplexity/extension/src/plugins/_core/main-world"
    click PLG_UIROOT "https://github.com/pnd280/complexity/tree/nxt/perplexity/extension/src/plugins/_core/ui"

    %% Click Events - UI Components
    click UI_SHARED "https://github.com/pnd280/complexity/tree/nxt/perplexity/extension/src/components"
    click SIDEBAR "https://github.com/pnd280/complexity/tree/nxt/perplexity/extension/src/entrypoints/options-page/components/sidebar"
    click DASH_PLUG "https://github.com/pnd280/complexity/tree/nxt/perplexity/extension/src/entrypoints/options-page/dashboard/pages/plugins"
    click THEMES "https://github.com/pnd280/complexity/tree/nxt/perplexity/extension/src/entrypoints/options-page/dashboard/pages/themes"
    click ONBOARD "https://github.com/pnd280/complexity/tree/nxt/perplexity/extension/src/entrypoints/options-page/onboarding"

    %% Click Events - Build & Delivery Tools
    click CLI_TOOL "https://github.com/pnd280/complexity/tree/nxt/perplexity/extension/cli"
    click VITE_CFG "https://github.com/pnd280/complexity/blob/nxt/perplexity/extension/vite.config.ts"
    click GULP "https://github.com/pnd280/complexity/blob/nxt/perplexity/extension/gulpfile.js"
    click E2E "https://github.com/pnd280/complexity/tree/nxt/perplexity/extension/e2e"
    click UNIT "https://github.com/pnd280/complexity/blob/nxt/perplexity/extension/tests/vitest.setup.ts"

    %% Styles
    classDef orchestrator fill:#D0E8FF,stroke:#0366d6
    classDef pkg fill:#E0F7FA,stroke:#006064
    classDef build fill:#F0F0F0,stroke:#888888
    classDef manifest fill:#FFF3CD,stroke:#FFEEBA
    classDef background fill:#FFE5B4,stroke:#FF8C00
    classDef contentscript fill:#E0FFE0,stroke:#00A000
    classDef options fill:#F5E6FF,stroke:#800080
    classDef service fill:#E0F7E0,stroke:#00796B
    classDef db fill:#E0F7E0,stroke:#00796B
    classDef api fill:#E0F7E0,stroke:#00796B
    classDef ui fill:#FFE4E1,stroke:#FF1493
    classDef plugin fill:#FFFACD,stroke:#DAA520
```
