How basshelal/wudooh works
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.