# zephyraft/mermaid-previewer architecture

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

- Interactive diagram: https://gitdiagram.com/zephyraft/mermaid-previewer
- Repository: https://github.com/zephyraft/mermaid-previewer

## Overview

##### Analyzing the File Structure
- The project is organized under the “src” directory, which is split into several main parts:
a. src/background – Contains background scripts (e.g., index.ts, messaging handlers like download.ts) responsible for running in the background and managing events and inter-component messaging.
c. src/core – Houses shared logic such as filtering, mutations, hover interactions, options handling, rendering, and selectors.
- Other files outside “src” (e.g., package.json, Tailwind, PostCSS, Playwright config, tests, etc.) indicate a rich development environment with testing, linting, and build configuration.

- Main Components:
- Options / UI: The settings or configuration pages that users interact with to adjust rules, selectors, and other extension parameters. They are built with modern React components.
- Core Logic: Shared modules (filter, mutation, render, selectors, etc.) provide essential business logic that drives both the background and content layers.

##### Relationships and Data Flow
- How Components Interact:
- The Background Scripts listen for user actions (e.g., exporting an image) and manage inter-script communications.
- The Options Page accesses and updates configuration settings that affect how content scripts operate (such as URL exclusion patterns and CSS selectors).
- Core modules are utilized by both background and content scripts to provide consistent behavior (e.g., applying filters or executing DOM mutations).
- Data flow: From the Content Scripts to the Background Scripts (e.g., message passing for exports).
- Dependency: Options Page updating configuration that is then used by Core modules and injected into Content Scripts.

##### Architectural Patterns and Technologies
- The project leverages the common Chrome Extension architectural pattern of separation between background, content, and options components.
- Use of TypeScript is evident (files ending with .ts and .tsx), which emphasizes type-safety and modular code.
- The build configuration (e.g., package.json, pnpm-lock.yaml, .nvmrc) indicates an organized front-end development process.
- The extension’s UI components are built with React (observed from .tsx files), while styling is handled by Tailwind (tailwind.config.js) and PostCSS.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Background Scripts Subgraph
    subgraph "Background Scripts"
        BG_Index("index.ts"):::background
        BG_Download("download.ts"):::background
    end

    %% Content Scripts Subgraph
    subgraph "Content Scripts"
        CS_Previewer("previewer.ts"):::content
        CS_Exporter("exporter.tsx"):::content
        CS_FontAwesome("fontawesome.css"):::content
        CS_Style("style.css"):::content
    end

    %% Core Modules Subgraph
    subgraph "Core Modules"
        Core_Filter("filter.ts"):::core
        Core_Hover("hover.ts"):::core
        Core_Mutation("mutation.ts"):::core
        Core_Options("options.ts"):::core
        Core_Render("render.ts"):::core
        Core_Selectors("selectors.ts"):::core
    end

    %% Options UI Subgraph
    subgraph "Options UI"
        Options_Index("index.tsx"):::options
        Options_Config("ConfigTable.tsx"):::options
        Options_Sidebar("Sidebar.tsx"):::options
        Options_Settings("Settings.tsx"):::options
    end

    %% External Components
    Mermaid("Mermaid Library"):::external
    Chrome("Chrome API"):::external

    %% Relationships
    %% Content Scripts interactions
    CS_Previewer -->|"calls"| Chrome
    CS_Exporter -->|"calls"| Chrome
    CS_Previewer -->|"renders"| Mermaid

    CS_Previewer -->|"uses"| Core_Render
    CS_Previewer -->|"uses"| Core_Filter
    CS_Exporter -->|"uses"| Core_Mutation
    CS_Exporter -->|"uses"| Core_Selectors

    %% Communication between Content and Background
    CS_Exporter -->|"exportReq"| BG_Download

    %% Options UI updating Core Modules
    Options_Index -->|"updates"| Core_Options
    Options_Config -->|"updates"| Core_Options
    Options_Settings -->|"updates"| Core_Options

    %% Background Scripts using Core configuration
    BG_Index -->|"reads"| Core_Options

    %% Class Definitions for styling
    classDef background fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef content fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef core fill:#FFD700,stroke:#000,stroke-width:1px;
    classDef options fill:#DDA0DD,stroke:#000,stroke-width:1px;
    classDef external fill:#F5F5F5,stroke:#000,stroke-width:1px;

    %% Click Events
    click BG_Index "https://github.com/zephyraft/mermaid-previewer/blob/master/src/background/index.ts"
    click BG_Download "https://github.com/zephyraft/mermaid-previewer/blob/master/src/background/messages/download.ts"
    click CS_Previewer "https://github.com/zephyraft/mermaid-previewer/blob/master/src/contents/previewer.ts"
    click CS_Exporter "https://github.com/zephyraft/mermaid-previewer/blob/master/src/contents/exporter.tsx"
    click CS_FontAwesome "https://github.com/zephyraft/mermaid-previewer/blob/master/src/contents/fontawesome.css"
    click CS_Style "https://github.com/zephyraft/mermaid-previewer/blob/master/src/contents/style.css"
    click Core_Filter "https://github.com/zephyraft/mermaid-previewer/blob/master/src/core/filter.ts"
    click Core_Hover "https://github.com/zephyraft/mermaid-previewer/blob/master/src/core/hover.ts"
    click Core_Mutation "https://github.com/zephyraft/mermaid-previewer/blob/master/src/core/mutation.ts"
    click Core_Options "https://github.com/zephyraft/mermaid-previewer/blob/master/src/core/options.ts"
    click Core_Render "https://github.com/zephyraft/mermaid-previewer/blob/master/src/core/render.ts"
    click Core_Selectors "https://github.com/zephyraft/mermaid-previewer/blob/master/src/core/selectors.ts"
    click Options_Index "https://github.com/zephyraft/mermaid-previewer/blob/master/src/options/index.tsx"
    click Options_Config "https://github.com/zephyraft/mermaid-previewer/blob/master/src/options/components/ConfigTable.tsx"
    click Options_Sidebar "https://github.com/zephyraft/mermaid-previewer/blob/master/src/options/components/Sidebar.tsx"
    click Options_Settings "https://github.com/zephyraft/mermaid-previewer/blob/master/src/options/pages/Settings.tsx"
```
