# n4ze3m/page-assist architecture

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

- Interactive diagram: https://gitdiagram.com/n4ze3m/page-assist
- Repository: https://github.com/n4ze3m/page-assist

## Overview

##### Main Project Components
- Browser Extension Entry Points:
– Multiple “entries” directories for Chrome, Firefox and side panel, indicating that the extension interacts with the browser via content scripts, background scripts, options pages, and side panels.
- User Interface (UI) Components:
- Service & Business Logic Layer:
– Found in src/services (e.g., action, application, chrome integration, TTS, search, etc.) and src/chain files that handle “chat-with-website” functionality.
- Data and State Management:
– Managed via src/store (with model, option, web UI) and local storage or a small database abstraction in src/db (for saving custom models, knowledge databases, vector stores).
- External Integrations:
– Integration with various local AI providers (Ollama, LM Studio, etc.) through dedicated modules in src/models, as well as utilities to communicate with external endpoints.
- Localization and Internationalization:
– Handling multiple languages is evident from the src/assets/locale and src/i18n directories.
- Utility and Helper Functions:
– A wide range of utility functions exist in src/utils, assisting in tasks like markdown conversion, OCR, notification sending, etc.
- Documentation & Configuration:
– The docs folder provides detailed usage, and configuration files (package.json, tsconfig.json, tailwind.config.js, etc.) support project setup and builds.

##### Relationships and Interactions
- The Browser Extension’s entry points (located in src/entries and src/entries-firefox) serve as the primary starting script which loads the extension interfaces (sidebar and web UI).
- These entry points interact with UI components (React components under src/components) to render the user interface.
- The UI components, in turn, use hooks (in src/hooks) to handle interactions and to maintain state managed by the store (src/store).
- Services (src/services) and utility libraries (src/libs and src/utils) act as the intermediary between the UI and external/local AI providers, APIs, or even local browser storage (db).
- Localization files and i18n support help display content in multiple languages.
- The extension’s background scripts and content scripts (e.g., files under src/chain and src/entries/*.ts) capture interactions from web pages and communicate with the UI components.

##### Architectural Patterns and Technologies
- Modular Architecture: Clear separation among UI, service logic, and data management.
- Component-Based UI: React-driven components make up the entire UI layer with dedicated layouts and options panels.
- Event-Driven Communication: Hooks and service modules handle asynchronous events (like user input, API calls, or background messages) between the extension and the hosted webpage.
- Localization and Internationalization: A dedicated directory structure for multiple language support shows a strong commitment to global usability.
- Integration with Local AI Providers: Abstracting different AI provider APIs using dedicated model modules (under src/models) and utility functions for enabling plug-and-play integration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser Extension Shell
    subgraph "Browser Extension Shell"
        CE["Chrome Entry Points"]:::extension
        FE["Firefox Entry Points"]:::extension
    end

    %% UI Layer
    subgraph "UI Layer"
        SU["Sidebar UI"]:::ui
        WU["Web UI"]:::ui
        GUC["General UI Components"]:::ui
        RLO["React Layouts & Options"]:::ui
    end

    %% Services & Business Logic Layer
    subgraph "Services & Business Logic"
        SM["Service Modules"]:::services
        HK["Hooks"]:::services
        CF["Chain Files"]:::services
    end

    %% Data Layer
    subgraph "Data Layer"
        SS["State Store"]:::data
        LDB["Local Database"]:::data
    end

    %% External Integrations
    subgraph "External Integrations"
        LAI["Local AI Providers"]:::external
        PU["Provider Utilities"]:::external
    end

    %% Localization
    subgraph "Localization"
        LA["Locale Assets"]:::localization
        I18N["i18n"]:::localization
    end

    %% Utilities & Helpers
    subgraph "Utilities & Helpers"
        UF["Utility Functions"]:::utilities
        LH["Library Helpers"]:::utilities
    end

    %% Documentation & Configuration
    subgraph "Documentation & Configuration"
        DOC["Project Documentation"]:::docs
        CFG["Configuration Files"]:::docs
    end

    %% Data Flow Connections
    CE -->|"loads"| SU
    CE -->|"launches"| WU
    FE -->|"loads"| SU
    FE -->|"launches"| WU

    GUC -->|"renders UI"| SU
    RLO -->|"composes UI"| WU

    SU -->|"triggers events"| HK
    WU -->|"triggers events"| HK

    HK -->|"calls services"| SM
    HK -->|"uses chat logic"| CF

    SM -->|"updates"| SS
    CF -->|"updates"| SS

    SM -->|"interacts with"| LAI
    SM -->|"calls"| PU

    SS -->|"stores state"| LDB

    LA -->|"supports UI"| GUC
    I18N -->|"supports UI"| RLO

    UF -->|"assists"| SM
    LH -->|"supports"| UF

    DOC -->|"details"| CFG

    %% Click Events
    click CE "https://github.com/n4ze3m/page-assist/tree/main/src/entries"
    click FE "https://github.com/n4ze3m/page-assist/tree/main/src/entries-firefox"
    click GUC "https://github.com/n4ze3m/page-assist/tree/main/src/components"
    click RLO "https://github.com/n4ze3m/page-assist/tree/main/src/components/Layouts"
    click SM "https://github.com/n4ze3m/page-assist/tree/main/src/services"
    click CF "https://github.com/n4ze3m/page-assist/tree/main/src/chain"
    click HK "https://github.com/n4ze3m/page-assist/tree/main/src/hooks"
    click SS "https://github.com/n4ze3m/page-assist/tree/main/src/store"
    click LDB "https://github.com/n4ze3m/page-assist/tree/main/src/db"
    click LAI "https://github.com/n4ze3m/page-assist/tree/main/src/models"
    click PU "https://github.com/n4ze3m/page-assist/tree/main/src/models/utils"
    click LA "https://github.com/n4ze3m/page-assist/tree/main/src/assets/locale"
    click I18N "https://github.com/n4ze3m/page-assist/tree/main/src/i18n"
    click UF "https://github.com/n4ze3m/page-assist/tree/main/src/utils"
    click LH "https://github.com/n4ze3m/page-assist/tree/main/src/libs"
    click DOC "https://github.com/n4ze3m/page-assist/tree/main/docs"
    click CFG "https://github.com/n4ze3m/page-assist/blob/main/package.json"

    %% Styles
    classDef extension fill:#FFE082,stroke:#FBC02D,stroke-width:2px;
    classDef ui fill:#BBDEFB,stroke:#1976D2,stroke-width:2px;
    classDef services fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;
    classDef data fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px;
    classDef external fill:#FFCDD2,stroke:#D32F2F,stroke-width:2px;
    classDef localization fill:#D1C4E9,stroke:#7B1FA2,stroke-width:2px;
    classDef utilities fill:#B2EBF2,stroke:#0097A7,stroke-width:2px;
    classDef docs fill:#E1BEE7,stroke:#8E24AA,stroke-width:2px;
```
