# albertocubeddu/extensionos architecture

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

- Interactive diagram: https://gitdiagram.com/albertocubeddu/extensionos
- Repository: https://github.com/albertocubeddu/extensionos

## Overview

##### Project Type and Purpose
- Extension | OS is a full-stack browser extension (Chrome MV3 via Plasmo) that embeds AI functionality into the user’s browsing context.
- It comprises a background service worker, injected UI (popup, side panel, context menu), and options/config pages.
- Purpose: let users select text → invoke an LLM (OpenAI, VAPI, Ollama, etc.) → display results inline without leaving the page.

##### Key Architectural Components
a. Browser Extension Host (Chrome MV3)
- Background Service Worker (background/index.ts, init.ts)
- Content/Injection Layer (plasmo automatically injects popup.tsx, sidepanel.tsx)
- Context Menus & Messaging (background/messages/*.ts)
- Storage (Plasmo Storage/localStorage for API keys & settings)
b. UI Components
- Popup UI (popup.tsx)
- Side Panel (sidepanel.tsx)
- Options Page & Sub-pages (options/*.tsx)
- Reusable React UI library (components/ui and components/blocks)
c. Business Logic & Utilities
- LLM Call Handlers (lib/openAITypeCall.ts, lib/vapiOutbound.ts)
- Configuration & Providers (lib/configurations, lib/providers)
- Helpers: anonymousTracking, clientUUID, context menu cleanup, XY calculations
d. External Services
- OpenAI, Claude, Together.ai, Groq, VAPI (HTTP/S requests from background worker)
- Local Ollama server (localhost:11434)
- Google identity (optional OAuth via chrome.identity)

##### Component Relationships & Data Flow
- User selects text on page → right-click → context menu item → event hits Background Worker
└─> Background Worker sends message (e.g., callOpenAIReturn) to content script/UI
- Background Worker reads settings from Storage → invokes LLM call via lib/openAITypeCall or lib/vapiOutbound
└─> HTTP request to chosen LLM endpoint (external cloud or local Ollama).
└─> On response, Worker posts result back to UI via sendToSidepanel or copyTextToClipboard.
- UI (Popup/Side Panel) listens for messages → renders result in React components.
- Options Page lets user configure providers, prompts, keys → writes into Storage → consumed by Worker & UI.

##### Architectural Patterns & Principles
- MV3 Service Worker pattern: short-lived background script handling all extension logic.
- Message‐based decoupling: clear chrome.runtime.sendMessage channel for cross‐component comms.
- Modular UI in React/TSX via Plasmo framework: separation of concerns between UI, logic, and storage.
- Provider abstraction: new LLMs/providers can be plugged in via lib/providers and options/promptFactory.
- Local‐first storage & privacy: user keys in localStorage, no server component.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Legend
    subgraph "Legend"
        direction TB
        A[Blue: Internals]:::internal
        B[Green: Storage/Config]:::storage
        C[Orange: External Services]:::external
    end

    %% User Selection Flow
    User["User"]:::external -->|select text & right-click| SelectionMenu["SelectionMenu"]:::internal
    click SelectionMenu "https://github.com/albertocubeddu/extensionos/blob/main/contents/SelectionMenu.tsx"

    subgraph "Browser Extension Host"
        direction TB
        SW["Service Worker"]:::internal
        click SW "https://github.com/albertocubeddu/extensionos/blob/main/background/index.ts"
        click SW "https://github.com/albertocubeddu/extensionos/blob/main/background/init.ts"

        subgraph "Context Menus & Messaging"
            direction TB
            CallOpenAIReturn["callOpenAIReturn"]:::internal
            click CallOpenAIReturn "https://github.com/albertocubeddu/extensionos/blob/main/background/messages/callOpenAIReturn.ts"
            CopyText["copyTextToClipboard"]:::internal
            click CopyText "https://github.com/albertocubeddu/extensionos/blob/main/background/messages/copyTextToClipboard.ts"
            IdentityMsg["identity"]:::internal
            click IdentityMsg "https://github.com/albertocubeddu/extensionos/blob/main/background/messages/identity.ts"
            OpenOptions["openOptionPage"]:::internal
            click OpenOptions "https://github.com/albertocubeddu/extensionos/blob/main/background/messages/openOptionPage.ts"
            OpenSidePanel["openSidePanel"]:::internal
            click OpenSidePanel "https://github.com/albertocubeddu/extensionos/blob/main/background/messages/openSidePanel.ts"
            SendLoading["sendLoadingAction"]:::internal
            click SendLoading "https://github.com/albertocubeddu/extensionos/blob/main/background/messages/sendLoadingAction.ts"
            SendToPanel["sendToSidepanel"]:::internal
            click SendToPanel "https://github.com/albertocubeddu/extensionos/blob/main/background/messages/sendToSidepanel.ts"
        end

        subgraph "Content Injection"
            direction TB
            CoreContent["core.tsx"]:::internal
            click CoreContent "https://github.com/albertocubeddu/extensionos/blob/main/contents/core.tsx"
        end
    end

    SelectionMenu -->|chrome.contextMenus.onClicked| SW
    SW -->|chrome.runtime.sendMessage| CallOpenAIReturn
    SW -->|chrome.runtime.sendMessage| CopyText
    SW -->|chrome.runtime.sendMessage| IdentityMsg
    SW -->|chrome.runtime.sendMessage| OpenOptions
    SW -->|chrome.runtime.sendMessage| OpenSidePanel
    SW -->|chrome.runtime.sendMessage| SendLoading
    SW -->|chrome.runtime.sendMessage| SendToPanel

    %% Storage & Config
    Storage["Plasmo Storage / localStorage"]:::storage
    Config["Global Config"]:::storage
    click Config "https://github.com/albertocubeddu/extensionos/blob/main/lib/configurations/globalConfig.ts"

    SW -->|"reads/writes"| Storage
    OptionsUI -->|"reads/writes"| Storage
    Popup -->|"getCurrentSettings"| Storage

    %% UI Layer
    subgraph "UI Components"
        direction TB
        Popup["Popup UI"]:::ui
        click Popup "https://github.com/albertocubeddu/extensionos/blob/main/popup.tsx"

        SidePanel["Side Panel"]:::ui
        click SidePanel "https://github.com/albertocubeddu/extensionos/blob/main/sidepanel.tsx"

        subgraph "Options Pages"
            direction TB
            OptionsMain["options.tsx"]:::ui
            click OptionsMain "https://github.com/albertocubeddu/extensionos/blob/main/options.tsx"
            OptionsHeader["OptionsHeader"]:::ui
            click OptionsHeader "https://github.com/albertocubeddu/extensionos/blob/main/options/OptionsHeader.tsx"
            OptionsGeneral["OptionsGeneral"]:::ui
            click OptionsGeneral "https://github.com/albertocubeddu/extensionos/blob/main/options/OptionsGeneral.tsx"
            OptionsAbout["OptionsAbout"]:::ui
            click OptionsAbout "https://github.com/albertocubeddu/extensionos/blob/main/options/OptionsAbout.tsx"
            OptionsSettings["OptionsSettings"]:::ui
            click OptionsSettings "https://github.com/albertocubeddu/extensionos/blob/main/options/OptionsSettings.tsx"
            LlmSettings["LlmSettings"]:::ui
            click LlmSettings "https://github.com/albertocubeddu/extensionos/blob/main/options/LlmSettings.tsx"
            MixtureAgents["OptionsMixtureOfAgents"]:::ui
            click MixtureAgents "https://github.com/albertocubeddu/extensionos/blob/main/options/OptionsMixtureOfAgents.tsx"
            PromptFactoryPage["OptionsPromptFactory"]:::ui
            click PromptFactoryPage "https://github.com/albertocubeddu/extensionos/blob/main/options/OptionsPromptFactory.tsx"
            VoiceSettings["VoiceSettingsOutbound"]:::ui
            click VoiceSettings "https://github.com/albertocubeddu/extensionos/blob/main/options/VoiceSettingsOutbound.tsx"

            subgraph "Prompt Factory Modules"
                direction TB
                HelpSheetContext["HelpSheetContext"]:::ui
                click HelpSheetContext "https://github.com/albertocubeddu/extensionos/blob/main/options/promptFactory/HelpSheetContext.tsx"
                HelpSheetFunc["HelpSheetFunctionality"]:::ui
                click HelpSheetFunc "https://github.com/albertocubeddu/extensionos/blob/main/options/promptFactory/HelpSheetFunctionality.tsx"
                ProviderInstr["ProviderInstruction"]:::ui
                click ProviderInstr "https://github.com/albertocubeddu/extensionos/blob/main/options/promptFactory/ProviderInstruction.tsx"
                ProviderVoiceInstr["ProviderVoiceInstruction"]:::ui
                click ProviderVoiceInstr "https://github.com/albertocubeddu/extensionos/blob/main/options/promptFactory/ProviderVoiceInstruction.tsx"
                VapiConfig["VapiSpecificConfiguration"]:::ui
                click VapiConfig "https://github.com/albertocubeddu/extensionos/blob/main/options/promptFactory/VapiSpecificConfiguration.tsx"

                subgraph "Prompt Factory Components"
                    direction TB
                    InstrSnippet["InstructionSnippet"]:::ui
                    click InstrSnippet "https://github.com/albertocubeddu/extensionos/blob/main/options/promptFactory/components/InstructionSnippet.tsx"
                end

                subgraph "Prompt Parameters"
                    direction TB
                    ChromeParams["chromeContextParameters"]:::ui
                    click ChromeParams "https://github.com/albertocubeddu/extensionos/blob/main/options/promptFactory/parameters/chromeContextParameters.tsx"
                    FuncParams["functionalityParameters"]:::ui
                    click FuncParams "https://github.com/albertocubeddu/extensionos/blob/main/options/promptFactory/parameters/functionalityParameters.tsx"
                end
            end

            subgraph "OAuth Modules"
                direction TB
                ExtensionLogin["ExtensionOsLogin"]:::ui
                click ExtensionLogin "https://github.com/albertocubeddu/extensionos/blob/main/options/settings/ExtensionOsLogin.tsx"
                GoogleBtn["GoogleButton"]:::ui
                click GoogleBtn "https://github.com/albertocubeddu/extensionos/blob/main/options/settings/GoogleButton.tsx"
                GoogleBtnDark["GoogleButtonDark"]:::ui
                click GoogleBtnDark "https://github.com/albertocubeddu/extensionos/blob/main/options/settings/GoogleButtonDark.tsx"
            end
        end
    end

    SW -->|openOptionPage| OptionsMain
    Popup -->|openOptionPage| OptionsMain
    SW -->|openSidePanel| SidePanel

    SidePanel -->|sendToSidepanel| SW
    Popup -->|getCurrentSettings| SW

    %% Business Logic & Utilities
    subgraph "Business Logic & Utilities"
        direction TB
        LLMOpenAI["openAITypeCall"]:::logic
        click LLMOpenAI "https://github.com/albertocubeddu/extensionos/blob/main/lib/openAITypeCall.ts"
        LLMVapi["vapiOutbound"]:::logic
        click LLMVapi "https://github.com/albertocubeddu/extensionos/blob/main/lib/vapiOutbound.ts"

        Providers["Providers Module"]:::logic
        click Providers "https://github.com/albertocubeddu/extensionos/blob/main/lib/providers/EmailShowcase.tsx"
        click Providers "https://github.com/albertocubeddu/extensionos/blob/main/lib/providers/UserInfoContext.tsx"

        Helpers["Helpers Module"]:::logic
        click Helpers "https://github.com/albertocubeddu/extensionos/blob/main/lib/anonymousTracking.ts"
        click Helpers "https://github.com/albertocubeddu/extensionos/blob/main/lib/clientUUID.ts"
        click Helpers "https://github.com/albertocubeddu/extensionos/blob/main/lib/cleanContextMenu.ts"
        click Helpers "https://github.com/albertocubeddu/extensionos/blob/main/lib/calculationXY.ts"
        click Helpers "https://github.com/albertocubeddu/extensionos/blob/main/lib/utils.ts"
    end

    SW -->|calls| LLMOpenAI
    SW -->|calls| LLMVapi
    LLMOpenAI -->|uses| Providers
    LLMVapi -->|uses| Providers
    SW -->|uses| Helpers

    %% External Services
    subgraph "External Services"
        direction TB
        CloudLLM["OpenAI / Claude / Groq"]:::external
        VapiSvc["VAPI"]:::external
        Ollama["Local Ollama (localhost:11434)"]:::external
        GoogleIdentity["Google Identity OAuth"]:::external
    end

    LLMOpenAI -->|HTTP/S| CloudLLM
    LLMVapi -->|HTTP/S| VapiSvc
    LLMOpenAI -->|HTTP/S| Ollama
    IdentityMsg -->|chrome.identity| GoogleIdentity

    %% Styles
    classDef internal fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef ui fill:#E8F4FF,stroke:#005B9A,color:#005B9A;
    classDef storage fill:#E6FFDD,stroke:#28A745,color:#28A745;
    classDef external fill:#FFE7C2,stroke:#D97706,color:#D97706;
    classDef logic fill:#F0E6FF,stroke:#8A2BE2,color:#8A2BE2;
```
