# basshelal/wudooh architecture

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

- Interactive diagram: https://gitdiagram.com/basshelal/wudooh
- Repository: https://github.com/basshelal/wudooh

## Overview

##### Project Type and Purpose
- Wudooh is a browser extension aimed at improving the display of Arabic script text. It allows users to customize fonts, sizes, line heights, and more. It supports multiple browsers (Chrome, Firefox, Edge, Opera) and manages localization (Arabic, Persian, Urdu, etc.).
- From the README and file tree, it’s clear that this is not a full-blown web application but an extension with separate concerns for UI, background processes, and asset management.

##### Break Down the File Structure and Determine Main Components
- Source Code Structure:
– /src directory: Contains the core TypeScript files that implement the extension’s logic (e.g., background.ts, popup.ts, newpopup.tsx, custom_fonts.ts, extensions.ts, plugins.ts). These are the heart of the extension’s functionality.
– /pages directory: Contains HTML pages and assets for different user interfaces such as popups, test pages, and locale files (found in pages/locales). This likely represents the extension’s options or settings pages (for fonts, customization, etc.) and localization support.
– /scripts directory: Provides specific entry points for various browsers (chrome.ts, firefox.ts, zip.ts) to create browser-specific builds and packaging.
– /webpack directory and configuration files (webpack.common.js, webpack.dev.js, webpack.prod.js): These represent the build pipeline that bundles, transpiles, and packages the extension code.
– Other directories (/fonts, .github, .idea) represent project housekeeping, fonts configuration, and community details that are less central to runtime architecture.

##### Main Components
- Browser Environment:
– The Web Browser acts as the host environment, where the extension is loaded.
– It has multiple entry points: the Browser Action (popup), Options/Settings pages, and injected content scripts.
- Extension Manifest & Configuration:
– The manifest.json (in public) controls extension permissions, declared scripts, and UI pages.
- UI Components:
– Popup UI: Built from files in /pages (e.g., popup.html, popup.css) and further enhanced by React/TSX components (newpopup.tsx in /src).
- Core Logic Components:
– Background Script: (src/background.ts) handles persistent event listeners, message passing, and initializes the extension.
– Content Scripts & Customizations: (src/custom_fonts.ts, src/extensions.ts) inject changes/styles into web pages to modify the display of Arabic script.
– Plugin/Module System: (src/plugins.ts) indicating extensibility and modular logic for handling different customizations.
- Browser-Specific Build Scripts:
– The /scripts directory contains specific TypeScript files (chrome.ts, firefox.ts, zip.ts) used to adjust configurations per browser.
- Build & Deployment Infrastructure:
– Webpack configuration: Bundles the various source components (both TypeScript and assets) into browser-ready bundles.
– Test files: (src/tests folder, jest.config.js) used for automated testing of core functionality.
- Localization & Asset Management:
– Localization Files: (pages/locales/*) providing support for different languages.
– Fonts Assets: (fonts directory and fonts within /public) hold configuration and CSS for custom font styling.

##### Relationships and Interactions
- Data Flow & Messaging:
– The Background Script continuously listens for browser events and messages from UI components.
– The Popup and Options UI trigger messages and API calls to the background process and content scripts.
– Content scripts inject or modify styles (custom fonts and CSS from public/ and pages/res) into web pages to update Arabic script visualization.
– Language/localization components interact with the UI to present localized text.
- Build Process & Deployment:
– Webpack compiles source code from /src with configurations for development and production, bundling it together.
– Browser-specific scripts (from /scripts) ensure that the correct extension version is built for different browsers.
- Dependency Management:
– Shared libraries and configurations (package.json dependencies and tsconfig.json settings) ensure a consistent environment across components.

##### Architectural Patterns & Design Principles
- Modularity: The clear separation between UI (popup, options pages) and background logic simplifies maintenance and testing.
- Layering: Presentation Layer (HTML/CSS/React in popup/newpopup) vs. Business Logic (background scripts and custom_modules) vs. Build/Deployment (Webpack pipelines).
- Cross-Browser Abstraction: The use of distinct scripts for Chrome, Firefox, etc., shows an emphasis on tailored adaptations for each environment.
- Extensibility: Plugins and modular organization in the /src directory point toward an architecture that can be easily extended or integrated with new features (like custom fonts or advanced settings).

- Drill down into the extension’s internal architecture by segmenting the logic into:
– UI Layer (Popup, Options, Localization UI)
– Core Logic Layer (Background Script, Content Injection, Plugins/Extensions)
– Asset and Resources (Fonts, CSS, Manifest, Localization Files)
- Finally, sketch out the workflow: User interacts with UI → UI sends commands via messaging to Background script → Background script coordinates with content scripts to modify page appearance → Fonts and styling are loaded from public/pages directories.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Development & Build Layer
    subgraph "Development & Build Layer"
        CoreLogic["Project Core Logic"]:::core
        BuildScripts["Browser-Specific Build Scripts"]:::build
        Webpack["Webpack Build Pipeline"]:::build
        Testing["Testing Infrastructure"]:::testing
        Localization["Localization Files"]:::assets
        FontAssets["Font Assets"]:::assets
    end

    %% Runtime Extension Layer
    subgraph "Runtime Extension Layer"
        Manifest["Extension Manifest & Configuration"]:::browser

        subgraph "UI Layer"
            PopupHTML["Popup UI (HTML)"]:::browser
            PopupCSS["Popup UI (CSS)"]:::browser
            NewPopupHTML["New Popup UI (HTML)"]:::browser
            NewPopupTS["New Popup UI (TS)"]:::browser
            AdditionalPages["Additional Pages"]:::browser
        end

        subgraph "Core Scripts"
            PopupScript["Popup Script"]:::browser
            BackgroundScript["Background Script"]:::browser
            ContentScripts["Content Scripts"]:::browser
            PluginsSystem["Plugins System"]:::browser
        end

        Browser["Web Browser"]:::browser
    end

    %% Development & Build Interactions
    CoreLogic --> Webpack
    BuildScripts --> Webpack
    Testing --> CoreLogic
    %% Webpack outputs the bundled extension to Manifest
    Webpack --> Manifest

    %% Link Core Logic to Runtime Scripts
    CoreLogic --> PopupScript
    CoreLogic --> BackgroundScript
    CoreLogic --> ContentScripts
    CoreLogic --> PluginsSystem

    %% Assets feed into Runtime
    Localization --> AdditionalPages
    FontAssets --> ContentScripts

    %% Manifest wiring within Runtime
    Manifest --> PopupHTML
    Manifest --> PopupCSS
    Manifest --> NewPopupHTML
    Manifest --> NewPopupTS
    Manifest --> AdditionalPages
    Manifest --> PopupScript
    Manifest --> BackgroundScript
    Manifest --> ContentScripts
    Manifest --> PluginsSystem

    %% UI actions
    PopupHTML --> PopupScript
    PopupCSS --> PopupScript
    NewPopupHTML --> PopupScript
    NewPopupTS --> PopupScript
    AdditionalPages --> PopupScript

    %% Background coordination
    PopupScript --> BackgroundScript
    BackgroundScript --> ContentScripts
    BackgroundScript --> PluginsSystem

    %% Final output to Browser
    Manifest --> Browser

    %% Click Events for Development & Build Layer
    click CoreLogic "https://github.com/basshelal/wudooh/tree/master//src"
    click BuildScripts "https://github.com/basshelal/wudooh/tree/master//scripts"
    click Webpack "https://github.com/basshelal/wudooh/tree/master//webpack"
    click Testing "https://github.com/basshelal/wudooh/tree/master//src/tests"
    click Localization "https://github.com/basshelal/wudooh/tree/master//pages/locales"
    click FontAssets "https://github.com/basshelal/wudooh/tree/master//fonts"

    %% Click Events for Runtime Extension Layer - Manifest & UI
    click Manifest "https://github.com/basshelal/wudooh/blob/master//public/manifest.json"
    click PopupHTML "https://github.com/basshelal/wudooh/blob/master//public/popup.html"
    click PopupCSS "https://github.com/basshelal/wudooh/blob/master//public/popup.css"
    click NewPopupHTML "https://github.com/basshelal/wudooh/blob/master//public/newpopup.html"
    click NewPopupTS "https://github.com/basshelal/wudooh/blob/master//src/newpopup.tsx"
    click AdditionalPages "https://github.com/basshelal/wudooh/tree/master//pages"

    %% Click Events for Runtime Extension Layer - Core Scripts
    click PopupScript "https://github.com/basshelal/wudooh/blob/master//src/popup.ts"
    click BackgroundScript "https://github.com/basshelal/wudooh/blob/master//src/background.ts"
    click ContentScripts "https://github.com/basshelal/wudooh/blob/master//src/extensions.ts"
    click PluginsSystem "https://github.com/basshelal/wudooh/blob/master//src/plugins.ts"

    %% Styles
    classDef browser fill:#B3E5FC,stroke:#0277BD,stroke-width:2px;
    classDef core fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef build fill:#FFE082,stroke:#FFA000,stroke-width:2px;
    classDef assets fill:#D1C4E9,stroke:#512DA8,stroke-width:2px;
    classDef testing fill:#F8BBD0,stroke:#AD1457,stroke-width:2px;
```
