# sagred/nano architecture

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

- Interactive diagram: https://gitdiagram.com/sagred/nano
- Repository: https://github.com/sagred/nano

## Overview

##### Main Components
- Chrome Extension Shell – Represent the extension’s integration points (manifest.json, background scripts, content-scripts, and the side panel page).
- User Interface – Consisting of React components (inside src/components) including the chat system, context menus, search bar, and UI components (alerts, buttons, cards, etc.).
- Background Services – Scripts located in src/background managing persistent tasks or extension lifecycle events.
- Content Scripts – Located in src/content-scripts that interact directly with web pages and gather page content for processing.
- Custom Hooks & APIs – Found in src/hooks and src/services (ai, bookmarks, embeddings, storage) providing core functionalities like AI capabilities, text modification, bookmark processing, and accessing storage.
- Utilities & Helpers – Including utils, lib, and configuration files that help script execution and development (e.g., vite.config.ts, postcss.config.js).

##### Relationships and Interactions
- That the manifest.json initializes the Chrome Extension and loads the background script along with the content scripts.
- React UI (found in the side panel, popup, and any other components) which interacts with the background/content layers and also directly calls the services (like AI integration, bookmarks management).
- Trace the data flow: User interactions in the UI (e.g., text selection, chat inputs) trigger hooks in React that then call corresponding services for processing (AI calls, IndexedDB access, etc.). The results propagate back to update UI components.
- External dependencies such as TensorFlow.js, the Universal Sentence Encoder, Cohere’s models (for fine-tuning and text classification), and any API layers.

##### Architectural Patterns & Design Principles
- Modular Architecture – Separation of concerns: each top-level directory (components, hooks, services) encapsulates specific functionality.
- Component Reusability – The UI components and custom hooks are organized to promote reusability and maintainability.
- Chrome Extension Model – Clearly distinguish background scripts, content scripts, and the extension’s UI (side panel/pop-up).
- Data Flow – Emphasize the unidirectional flow in the React components using hooks that interact with services, ensuring state consistency.

##### Mirror the Specific Technologies
- Frontend Technologies: React, TypeScript, and Tailwind CSS to be visually represented in the UI layer.
- AI & Machine Learning: Indicate the integration points for TensorFlow.js, the Universal Sentence Encoder, and Cohere.
- Storage: Show how IndexedDB (via Dexie.js) and Chrome Storage are part of the persistence layer.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Chrome Extension Shell
    subgraph "Chrome Extension Shell"
        M["Manifest.json"]:::chrome
        BS["Background Script"]:::chrome
        CS["Content Script"]:::chrome
        SPH["Side Panel HTML"]:::chrome
        SPT["Side Panel TSX"]:::chrome
    end

    %% User Interface Layer
    subgraph "User Interface"
        AE["App Entry"]:::frontend
        RC["React Components"]:::frontend
    end

    %% Business Logic and Helpers
    subgraph "Business Logic"
        CH["Custom Hooks"]:::logic
        AS["APIs & Services"]:::logic
        UT["Utils"]:::utilities
        LU["Lib Utils"]:::utilities
        VC["Vite Config"]:::utilities
        PC["PostCSS Config"]:::utilities
        AI["AI Services"]:::external
        ST["Storage"]:::external
    end

    %% Connections for Chrome Extension Shell
    M -->|"loads"| BS
    M -->|"loads"| CS
    M -->|"loads"| SPH
    M -->|"loads"| SPT

    %% Connection from Chrome Shell UI to App Layer
    SPH -->|"hosts"| AE
    SPT -->|"hosts"| AE

    %% UI Flow
    AE -->|"renders"| RC
    RC -->|"triggers"| CH

    %% Business Logic interactions
    CH -->|"calls"| AS
    CH -->|"utilizes"| UT
    CH -->|"utilizes"| LU
    CH -->|"utilizes"| VC
    CH -->|"utilizes"| PC
    AS -->|"integrates"| AI
    AS -->|"accesses"| ST

    %% Communication between Content and Background scripts
    CS -->|"messages"| BS

    %% Click Events
    click M "https://github.com/sagred/nano/blob/main/manifest.json"
    click BS "https://github.com/sagred/nano/blob/main/src/background/index.ts"
    click CS "https://github.com/sagred/nano/blob/main/src/content-scripts/index.ts"
    click SPH "https://github.com/sagred/nano/blob/main/src/sidepanel.html"
    click SPT "https://github.com/sagred/nano/blob/main/src/sidepanel.tsx"
    click AE "https://github.com/sagred/nano/blob/main/src/App.tsx"
    click RC "https://github.com/sagred/nano/tree/main/src/components"
    click CH "https://github.com/sagred/nano/tree/main/src/hooks"
    click AS "https://github.com/sagred/nano/tree/main/src/services"
    click UT "https://github.com/sagred/nano/tree/main/src/utils"
    click LU "https://github.com/sagred/nano/blob/main/src/lib/utils.ts"
    click VC "https://github.com/sagred/nano/blob/main/vite.config.ts"
    click PC "https://github.com/sagred/nano/blob/main/postcss.config.js"

    %% Styles
    classDef chrome fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef frontend fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef logic fill:#87CEEB,stroke:#000,stroke-width:2px;
    classDef utilities fill:#FFE4B5,stroke:#000,stroke-width:2px;
    classDef external fill:#DDA0DD,stroke:#000,stroke-width:2px;
```
