# builderio/figma-html architecture

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

- Interactive diagram: https://gitdiagram.com/builderio/figma-html
- Repository: https://github.com/builderio/figma-html

## Overview

##### Project Type and Purpose
- The project is a Chrome extension related to converting or translating HTML to Figma designs.
- Although the README notes that the project has moved to the Builder.io chrome extension, our focus remains on the internal architecture of this code—namely, the chrome-extension module and its supporting components.
- The purpose is to integrate with web pages (using inject scripts), provide UI via a popup, and run background logic as part of a Chrome extension.

##### File Structure
- The root level contains general configuration files (like package.json, LICENSE.md, tsconfig.json, webpack.config.js) and documentation (.github, DEVELOP.md).
- The main application code lives inside the chrome-extension folder. This folder holds:
- A manifest file (chrome-extension/info/manifest.json) that defines the extension’s permissions, scripts, and assets.
- UI components such as the popup (chrome-extension/src/popup) including Popup.tsx and index.tsx, plus HTML assets (chrome-extension/info/popup.html).
- The background script (chrome-extension/src/background.ts) responsible for long-running processes or communication with other pages.
- The injection script (chrome-extension/src/inject.ts), likely used to interact with web page content.
- Additional supporting elements like constants (chrome-extension/src/constants/theme.ts) to manage theme or configuration settings.
- Shared types under the shared folder provide TypeScript definitions used across various parts of the project.

##### High-Level Architectural Components
a. Chrome Extension Core:
- Manifest (defines the chrome extension configuration and permissions).
- Background Script (handles event listeners and background tasks).
- Content Script/Injection Logic (runs in the context of web pages).
- Popup UI (user interface when the extension is activated).
b. Shared Code and Configurations:
- Shared Type Definitions (for ensuring consistency in data structures).
- Build configuration (webpack and TypeScript configuration files that bundle and compile the project).
- Other development supports (e.g., .nvmrc, CODEOWNERS).

##### Relationships and Interactions
- The popup communicates with the background script via Chrome’s message-passing APIs to request data or trigger background processes.
- The injection script may directly interact with the current webpage’s DOM, potentially passing messages back to the background script if needed.
- All components are bundled using webpack (with separate configurations for development and production) and compiled with TypeScript settings defined in tsconfig.json.
- The manifest file ties together these scripts, specifying when and how each part of your code runs inside the Chrome environment.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Each Chrome extension component (background, popup, inject) is clearly separated with dedicated logic and responsibilities.
- Event-Driven Architecture: Communication between the popup and background script uses asynchronous messaging events, a common Chrome extension pattern.
- Modularity: Using shared type definitions and grouping by function (constants in one folder, popup components in another) enhances maintainability and scalability.
- Bundling Best Practices: The use of webpack, along with separate configuration files (webpack.common.js, webpack.dev.js, webpack.prod.js), implies an architectural emphasis on environment-specific optimization.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build and Configuration Layer
    subgraph "Build Tools"
        BT1("Webpack Config"):::build
        BT2("TypeScript Config (Root)"):::build
        BT3("Chrome Extension TSConfig"):::build
    end

    %% Chrome Extension Core Components
    subgraph "Chrome Extension Core"
        M("Configuration Hub (Manifest)"):::config
        BS("Background Script"):::background
        IS("Injection Script"):::inject
        %% Popup UI as a nested subgraph
        subgraph "Popup UI"
            PU1("React Popup Component"):::ui
            PU2("Popup HTML"):::ui
        end
    end

    %% Shared Modules
    subgraph "Shared Modules"
        ST1("Shared Typings (.d.ts)"):::shared
        ST2("Shared Typings (.ts)"):::shared
        TC("Theme/Constants"):::constants
    end

    %% Build Tools connecting to Core Components
    BT1 -->|"BundlesExtension"| M
    BT1 -->|"BundlesExtension"| BS
    BT1 -->|"BundlesExtension"| IS
    BT1 -->|"BundlesExtension"| PU1

    BT2 -->|"CompilesCode"| M
    BT2 -->|"CompilesCode"| BS
    BT2 -->|"CompilesCode"| IS
    BT2 -->|"CompilesCode"| PU1

    BT3 -->|"CompilesExtension"| M
    BT3 -->|"CompilesExtension"| BS
    BT3 -->|"CompilesExtension"| IS
    BT3 -->|"CompilesExtension"| PU1

    %% Manifest defines entry points for components
    M -->|"EntryFor_Background"| BS
    M -->|"EntryFor_Inject"| IS
    M -->|"EntryFor_Popup"| PU1

    %% Communication between components
    PU1 <-->|"msgPassing"| BS
    BS -->|"Trigger_DOM_Action"| IS

    %% Shared Modules usage
    ST1 -.->|"ProvidesTypes"| BS
    ST1 -.->|"ProvidesTypes"| PU1
    ST1 -.->|"ProvidesTypes"| IS

    ST2 -.->|"ProvidesTypes"| BS
    ST2 -.->|"ProvidesTypes"| PU1
    ST2 -.->|"ProvidesTypes"| IS

    TC -.->|"ProvidesTheme"| BS
    TC -.->|"ProvidesTheme"| PU1
    TC -.->|"ProvidesTheme"| IS

    %% Click Events
    click M "https://github.com/builderio/figma-html/blob/master/chrome-extension/info/manifest.json"
    click BS "https://github.com/builderio/figma-html/blob/master/chrome-extension/src/background.ts"
    click IS "https://github.com/builderio/figma-html/blob/master/chrome-extension/src/inject.ts"
    click PU1 "https://github.com/builderio/figma-html/tree/master/chrome-extension/src/popup"
    click PU2 "https://github.com/builderio/figma-html/blob/master/chrome-extension/info/popup.html"
    click TC "https://github.com/builderio/figma-html/blob/master/chrome-extension/src/constants/theme.ts"
    click ST1 "https://github.com/builderio/figma-html/blob/master/shared/typings.d.ts"
    click ST2 "https://github.com/builderio/figma-html/blob/master/shared/typings.ts"
    click BT1 "https://github.com/builderio/figma-html/blob/master/chrome-extension/webpack.common.js"
    click BT2 "https://github.com/builderio/figma-html/blob/master/tsconfig.json"
    click BT3 "https://github.com/builderio/figma-html/blob/master/chrome-extension/tsconfig.json"

    %% Styles
    classDef build fill:#fef3bd,stroke:#d08,stroke-width:2px;
    classDef config fill:#cce5ff,stroke:#003366,stroke-width:2px;
    classDef background fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef inject fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef ui fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef shared fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef constants fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
```
