# 99mini/widget-chrome-extension architecture

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

- Interactive diagram: https://gitdiagram.com/99mini/widget-chrome-extension
- Repository: https://github.com/99mini/widget-chrome-extension

## Overview

This project is a Chrome Extension called “Widget Chrome Extension” that provides a customizable new tab page featuring several types of widgets (e.g., clock, history, Google search, bookmarks). The project leverages modern web technologies such as React, Vite, TypeScript, and Emotion, and relies on the chrome manifest v3 API for the extension functionalities.

##### Project Type and Purpose
- This is a full-fledged Chrome Extension. Its primary purpose is to let users customize their new tab page by adding, editing, and managing various widgets.
- The extension includes multiple front-end interfaces (new tab, popup) and interacts with chrome-specific APIs for bookmarks, history, sessions, etc.

##### File Structure
- Notice top-level folders such as:
- “src” where the application’s TypeScript and React code resides.
- “public” which contains assets such as manifest.json, images, and other static files.
- “__test__” for testing utilities.
- “docs” that may include design assets.
- Inside “src”, distinguish the following key directories:
- “src/chrome”: Handles interactions with various chrome APIs (bookmarks, history, sessions, storage).
- “src/context”: Implements React context providers (such as ThemeProvider and DndProvider) which manage application state and inter-component communication.
- “src/popup” and “src/newTab”: Represent the two main entry points/pages (popup and new tab) for the extension.
- “src/hook” and “src/utils”: Provide custom hooks and helper functions that encapsulate business logic.

##### Main Components
- Chrome Extension Front-end:
- New Tab Page: Rendered via “src/newTab/index.tsx” that displays the dashboard of widgets.
- Popup: Rendered via “src/popup/index.tsx” that might be used for quick interactions.
- UI and Widget Management:
- UI Containers and Components: Organized under “src/components” (Header, Footer, modals, context menus, etc.)
- Widget Modules: Each widget type (clock, history, folder, google search, todo) is built as a separate component within “src/components/widget/*”. They have their own dedicated subdirectories indicating specialized functionality.
- Modal/Widget Creation: The “src/components/createModal” directory suggests a dedicated modal system for creating/editing widgets.
- State Management:
- React Context Providers: Located in “src/context”, these provide theming (dark mode, i18n) and drag-and-drop (DndProvider) support across the application.
- Chrome API Communication:
- The “src/chrome” folder contains modules that interface with the chrome extension APIs (for bookmarks, history, sessions, storage) that enable the integration between system data and the UI.
- Build and Development:
- Configuration and build scripts (scripts in “.scripts”), configuration files (vite.config.ts, tsconfig.json, etc.) and test directories indicate robust development and testing practices.
- The use of Vite and Yarn is integral to the development flow.

##### Relationships and Interactions
- That these UI components are enhanced by state provided by React contexts, which manage theme and drag-and-drop support.
- Testing suite (__test__) and development tooling as peripheral components that support the development lifecycle.

##### Architectural Patterns and Design Principles
- Component-Based Architecture: Highlight that the UI is built as reusable components (with a clear separation between common UI elements, widget-specific UI, and modal interactions).
- Separation of Concerns: Display separation between UI rendering, business logic (hooks and utils), state management (context providers), and external communication (chrome APIs).
- Modular Design: Capture the independent modules for different widget types and utility functions.

##### Technology Stack and Their Roles
- React and TypeScript: Fundamental for creating the UI components and ensuring type safety.
- Vite: For efficient module bundling and development server.
- Emotion: For CSS-in-JS styling of components.
- Yarn: As the package manager, with a specific version noted (4.2.2).
- Shadcn/ui and other UI libraries/components integrated to support user interface consistency.
- Chrome API: To interact with bookmarks, history, sessions, etc., to support extension functionalities.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interfaces"
        A["New Tab UI"]:::ui
        B["Popup UI"]:::ui
        B1["Popup App"]:::ui_aux
    end

    subgraph "UI Components & Widgets"
        C["UI Containers & Common Components"]:::ui
        subgraph "Widget Modules"
            D["Clock Widget"]:::widget
            E["History Widget"]:::widget
            F["Folder Widget"]:::widget
            G["Google Search Widget"]:::widget
            H["Todo Widget"]:::widget
            I["Icon Widget"]:::widget
        end
        J["Widget Creation Modal"]:::widget_modal
    end

    K["React Context Providers"]:::state
    L["Chrome API Integration"]:::api
    M["Build & Development Tools"]:::dev

    K --> A
    K --> B
    A --> C
    B --> C
    B --> B1
    C --> J
    C --> D
    C --> E
    C --> F
    C --> G
    C --> H
    C --> I

    D --> L
    E --> L
    F --> L
    G --> L
    H --> L
    I --> L

    M --> K
    M --> C
    M --> L

    click A "https://github.com/99mini/widget-chrome-extension/blob/main/src/newTab/index.tsx"
    click B "https://github.com/99mini/widget-chrome-extension/blob/main/src/popup/index.tsx"
    click B1 "https://github.com/99mini/widget-chrome-extension/blob/main/src/popup/App.tsx"
    click C "https://github.com/99mini/widget-chrome-extension/tree/main/src/components"
    click D "https://github.com/99mini/widget-chrome-extension/blob/main/src/components/widget/clock/ClockWidget.tsx"
    click E "https://github.com/99mini/widget-chrome-extension/blob/main/src/components/widget/history/HistoryWidget.tsx"
    click F "https://github.com/99mini/widget-chrome-extension/blob/main/src/components/widget/folder/FolderWidget.tsx"
    click G "https://github.com/99mini/widget-chrome-extension/blob/main/src/components/widget/google/GoogleSearchWidget.tsx"
    click H "https://github.com/99mini/widget-chrome-extension/blob/main/src/components/widget/todo/TodoWidget.tsx"
    click I "https://github.com/99mini/widget-chrome-extension/blob/main/src/components/widget/icon/IconWidget.tsx"
    click J "https://github.com/99mini/widget-chrome-extension/tree/main/src/components/createModal"
    click K "https://github.com/99mini/widget-chrome-extension/tree/main/src/context"
    click L "https://github.com/99mini/widget-chrome-extension/tree/main/src/chrome"
    click M "https://github.com/99mini/widget-chrome-extension/blob/main/.scripts"

    classDef ui fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef ui_aux fill:#D6EAF8,stroke:#1B4F72,stroke-width:2px;
    classDef widget fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef widget_modal fill:#FCF3CF,stroke:#B9770E,stroke-width:2px;
    classDef state fill:#A9DFBF,stroke:#145A32,stroke-width:2px;
    classDef api fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef dev fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
```
