Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page:

• src/main/index.ts
• src/preload/index.ts
• src/main/themes.ts
• src/preload/settings-modal.ts
• AGENTS.md
• CLAUDE.md

Messenger Unleashed is an Electron-based desktop application designed as an enhanced wrapper for the Facebook Messenger web platform. Its primary purpose is to provide a native-feeling desktop experience while injecting advanced features such as privacy controls, custom styling, and productivity tools that are absent from the standard web or official desktop versions.

The architecture follows the standard Electron multi-process model, consisting of a Main process for application logic and window management, and a Preload bridge that securely connects the renderer (the Messenger web view) to native system capabilities. The application emphasizes non-intrusive modification, relying heavily on CSS injection and JavaScript interception rather than a heavy frontend framework.

Sources: CLAUDE.md:5-10, AGENTS.md:4-10

Process Model and Communication

The application is structured into three primary layers: the Main process, the Preload Script, and the Renderer (Messenger.com).

Component Interaction

The following diagram illustrates the high-level interaction between the Electron processes and the external Messenger web content:

Main Process (src/main/index.ts)

The Main process acts as the application's orchestrator. It handles the lifecycle of the BrowserWindow, manages system tray integration, defines the application menu, and persists user settings via electron-store. It is also responsible for sensitive operations like managing network requests through the webRequest API to block trackers and read receipts.

Sources: src/main/index.ts:1-50, AGENTS.md:4-10, CLAUDE.md:15-20

Preload Script (src/preload/index.ts)

The Preload script serves as a security-isolated bridge. It utilizes contextBridge to expose specific, controlled APIs to the Messenger renderer. Its key architectural roles include:

• WebSocket Interception: Intercepting and filtering outgoing WebSocket frames to block typing indicators and active status updates at the protocol level.
• DOM Monitoring: Using MutationObserver to detect incoming messages for keyword alerts and unsend detection.
• Visibility Patching: Overriding document.visibilityState and document.hidden to prevent Messenger from knowing if the window is active, thereby blocking automated read receipts.

Sources: src/preload/index.ts:1-150, src/preload/index.ts:500-550, CLAUDE.md:38-42

Core Systems and Logic

Configuration and Persistence

Persistence is managed through electron-store. Settings are updated via a centralized update-setting IPC handler in the main process, which triggers side effects such as refreshing the UI or updating request filters.

Setting Component	Description	Implementation
Electron Store	Local JSON storage for user preferences.	src/main/state.ts
Feature Toggles	Logic to enable/disable specific privacy or UI enhancements.	toggle[Feature] functions in src/main/index.ts
Defaults Object	Initial configuration for new installations.	CLAUDE.md lines 18-20

Sources: src/main/index.ts:1000-1100, CLAUDE.md:17-23

Stealth and Privacy System

The stealth system uses a multi-layered approach to block telemetry and user-activity signals.

The system blocks two primary signals:

1. Read Receipts: Blocked by combining a webRequest.onBeforeRequest filter for specific URL patterns (e.g., mark_seen.php) and a JavaScript override in the preload that forces the page to believe it is hidden.
2. Typing Indicators: Blocked by a WebSocket proxy in the preload that drops frames containing the is_typing payload and a request blocker in the main process for GraphQL mutations.

Sources: src/main/index.ts:250-350, src/preload/index.ts:60-120, src/preload/index.ts:500-530

Theme and UI Modification System

UI customization is achieved through dynamic CSS injection. The themes.css file contains various theme "slices" marked by comments (e.g., /* oled */).

• Extraction: getThemeCSS(theme) uses regex to extract the specific block from themes.css.
• Injection: applyThemeCSS(theme) uses Electron's insertCSS with a specific cssKey ("theme") to allow hot-swapping without reloading the page.
• Advanced Modes: Features like "Modern Look" and "Floating Glass" use complex CSS strings injected directly from the main process to implement glassmorphism and layout changes.

Sources: src/main/themes.ts:35-60, src/main/index.ts:1500-1650, CLAUDE.md:44-50

User Interface Components

Settings Modal Architecture

The settings interface is not a separate Electron window but a sandboxed DOM overlay injected into the renderer.

Key UI elements are constructed dynamically using document.createElement within src/preload/settings-modal.ts. This allows settings to be adjusted without leaving the chat interface.

Sources: src/preload/settings-modal.ts:5-150

Native Integrations

The app integrates with the host OS through several Electron APIs:

• Tray: Provides a persistent icon in the menu bar/system tray, allowing the app to run in "Menu Bar Mode".
• Notifications: Overrides the native window.Notification constructor to route alerts through the Main process, respecting "Do Not Disturb" settings.
• Global Shortcuts: Uses globalShortcut to register hotkeys for Focus Mode, PiP, and Quick Replies.

Sources: src/main/index.ts:680-750, src/main/index.ts:1800-1850, src/preload/index.ts:550-580

Summary

Messenger Unleashed architecture is centered on the concept of a "Stealth Wrapper." By isolating Messenger's web code within a BrowserWindow and strictly controlling its environment through the Main/Preload bridge, the application successfully provides advanced privacy and customization features while maintaining compatibility with the underlying Messenger platform. The use of CSS injection and WebSocket interception allows these features to be updated or toggled instantly without frequent app reloads.

Sources: CLAUDE.md:70-80, AGENTS.md:1-5