# iamakchavan/harv architecture

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

- Interactive diagram: https://gitdiagram.com/iamakchavan/harv
- Repository: https://github.com/iamakchavan/harv

## Overview

##### Main Components
- Browser Extension Core: Start with the manifest (manifest.json) which outlines the extension’s permissions, background scripts, and UI pages. This acts as the entry point for your architecture.
- Frontend/UI: Represent the static HTML files (index.html, popup.html) and the React application (src/App.tsx), along with its components (the entire src/components/ folder). These elements compose the user interface – including components like FloatingSearch, Header, and ModelSelector.
- Background Process: Indicate the background script (src/background.ts) that runs persistently to handle tasks such as monitoring browser events and managing communication between the extension’s UI and the external services.
- Content Scripts: Include the content script (src/content.tsx) that may interact with web pages to perform tasks like on-page analysis or text selection features.
- Utility and AI Providers: Illustrate the utilities in src/utils (like ai-config.ts, ai.ts, tts.ts, url-analyzer.ts) and specific AI provider modules (src/utils/ai-providers/*). These handle API integrations, model switching, and processing logic.

##### Relationships and Data Flow
- From the UI layer, show that user interactions (e.g., smart search and text selection) trigger events that flow to the background process or directly call utility functions.
– UI Interaction → Background/Content Script → AI Utility Modules → External AI APIs (Gemini, Perplexity, xAI)
- Bidirectional communication if the background scripts are relaying results back to the UI.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Demonstrate how the project separates UI components, background processes, and utility logic for clarity and maintainability.
- Modular Design: Emphasize that each AI model provider is encapsulated within its own module, allowing for easier swapping or updating.
- Event-Driven Communication: Represent how user actions (keyboard shortcuts, selections) trigger events handled by the background script and then dispatched to the UI components.
- Use of React for dynamic UI rendering and Tailwind CSS (configured via tailwind.config.js) for styling, ensuring a modern frontend development approach.

##### Incorporate Technologies, Frameworks, and Libraries
- React / TypeScript: Core technologies driving the frontend (e.g., components in src/components/ and main application logic in src/App.tsx).
- Vite: The project uses Vite as its build tool, evidenced by vite.config.ts and tsconfig files.
- Tailwind CSS: Utilized for styling, as seen in tailwind.config.js and the inclusion of src/index.css.
- Node/NPM: Shown by the package.json and associated configuration files (postcss.config.js, eslint.config.js).

##### Elements
- Labels: Each component should be clearly labeled (e.g., “Background Script”, “Popup UI”, “Content Script”, “AI Provider: Gemini”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser Extension Core
    subgraph "Browser Extension Core"
        M["manifest.json"]:::core
    end

    %% UI Layer
    subgraph "UI Layer"
        I["index.html"]:::ui
        P["popup.html"]:::ui
        A["src/App.tsx"]:::ui
        RC["React Components"]:::ui
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        BS["Background Script"]:::bl
        CS["Content Script"]:::bl
    end

    %% Utilities Layer
    subgraph "Utilities Layer"
        U["Utils Modules"]:::util
        AP["AI Providers"]:::util
    end

    %% External AI Services
    subgraph "External AI Services"
        GEM["Gemini API"]:::ext
        PER["Perplexity API"]:::ext
        XAI["xAI API"]:::ext
    end

    %% Static Assets
    subgraph "Static Assets"
        SA["Static Assets"]:::assets
    end

    %% Connections from Manifest to UI and Business Logic
    M -->|"defines"| I
    M -->|"defines"| P
    M -->|"defines"| A
    M -->|"defines"| BS

    %% UI interactions trigger business logic
    I -->|"triggers"| BS
    P -->|"triggers"| BS
    A -->|"triggers"| BS
    RC -->|"triggers"| BS

    %% Business Logic invoking Utilities
    BS -->|"calls"| U
    CS -->|"calls"| U

    %% Utilities delegating to AI Providers
    U -->|"selects"| AP

    %% AI Providers invoking External AI Services
    AP -->|"requests"| GEM
    AP -->|"requests"| PER
    AP -->|"requests"| XAI

    %% External AI Services returning responses to Background Script
    GEM -->|"response"| BS
    PER -->|"response"| BS
    XAI -->|"response"| BS

    %% Business Logic relaying results back to UI
    BS -->|"updates"| RC
    CS -->|"updates"| RC

    %% Click Events
    click M "https://github.com/iamakchavan/harv/blob/master/manifest.json"
    click I "https://github.com/iamakchavan/harv/blob/master/index.html"
    click P "https://github.com/iamakchavan/harv/blob/master/popup.html"
    click A "https://github.com/iamakchavan/harv/blob/master/src/App.tsx"
    click RC "https://github.com/iamakchavan/harv/tree/master/src/components/"
    click BS "https://github.com/iamakchavan/harv/blob/master/src/background.ts"
    click CS "https://github.com/iamakchavan/harv/blob/master/src/content.tsx"
    click U "https://github.com/iamakchavan/harv/tree/master/src/utils/"
    click AP "https://github.com/iamakchavan/harv/tree/master/src/utils/ai-providers/"
    click SA "https://github.com/iamakchavan/harv/tree/master/public/icons"

    %% Styles
    classDef core fill:#ffe6e6,stroke:#cc0000,stroke-width:2px;
    classDef ui fill:#e6f2ff,stroke:#0066cc,stroke-width:2px;
    classDef bl fill:#e6ffe6,stroke:#009933,stroke-width:2px;
    classDef util fill:#fff2e6,stroke:#cc6600,stroke-width:2px;
    classDef ext fill:#fce6f5,stroke:#cc0099,stroke-width:2px;
    classDef assets fill:#f2f2f2,stroke:#666666,stroke-width:2px;
```
