# fajarnadril/overlaybrowser architecture

> Architecture diagram of the GitHub repository fajarnadril/overlaybrowser, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fajarnadril/overlaybrowser
- Repository: https://github.com/fajarnadril/overlaybrowser

## Overview

1. **What this repo is**
   - This is a **desktop Electron application**, not a web backend or server app.
   - Its core job is to provide a **floating, always-on-top browser overlay** that can be toggled globally and persisted locally.

2. **Top-level runtime boundary**
   - The app is split into **Electron main process** and one or more **renderer processes**.
   - `main.js` owns OS integration, window lifecycle, global shortcuts, and IPC routing.
   - UI and browser interactions live in the renderers, with preload scripts acting as the security boundary.

3. **Main orchestration layer**
   - `main.js` is the central controller.
   - It likely creates and manages the primary overlay window, registers the global shortcut, applies always-on-top/docking behavior, and restores saved state on startup.
   - This is the place where app-wide state transitions originate: show/hide, dock left/right, and persistence updates.

4. **Primary browser UI**
   - `index.html` and `renderer.js` form the main overlay UI.
   - This UI appears to handle URL entry, navigation, and profile-related actions exposed by the main process.
   - From an architecture diagram perspective, this is the user-facing browser surface that talks outward only through IPC.

5. **Secure renderer-to-main bridge**
   - `preload.js` is the API boundary for the main browser window.
   - It exposes a limited, safe set of methods into the renderer instead of giving direct Node access.
   - This is important because Electron’s trust boundary is between the renderer and the main process, and this repo explicitly uses preload scripts to enforce that.

6. **Floating control window subsystem**
   - `float-button.html`, `float-renderer.js`, and `float-preload.js` form a separate lightweight UI surface.
   - This appears to be the floating control layer for docking and window control, separate from the primary browser content.
   - In an architecture diagram, treat it as a second renderer window that sends control commands back to `main.js`.

7. **Data flow between UI and process layer**
   - User actions in `renderer.js` or `float-renderer.js` go through their respective preload bridges.
   - Those bridges call into `main.js` via IPC.
   - `main.js` then performs privileged operations such as window manipulation, shortcut handling, and profile persistence.

8. **Persistence model**
   - `profiles.json` is included as an example/documentation artifact for saved profile structure.
   - The actual runtime storage is described as Electron’s `userData` directory, which is local to the machine and platform-specific.
   - The persistent data appears to include URL, dock position, and window state, so the architecture includes a small local state store rather than any remote service.

9. **OS integration boundary**
   - A key architectural feature is the **global keyboard shortcut** for toggling the overlay.
   - That shortcut is registered at the OS level by the main process, so the app can be shown/hidden from anywhere.
   - This makes the OS the entry point for one major control path, separate from the UI.

10. **Deployment/build shape**
   - The repo is packaged as an Electron app using `electron-builder` via `package.json`.
   - `npm start` runs the app in development; build outputs are platform installers/artifacts.
   - This means the architecture is a single local desktop binary with embedded Chromium content, not a client/server deployment.

11. **Important architectural boundary**
   - There is **no backend service** in this repository.
   - All behavior is local: window management, user interaction, browser navigation, and profile storage happen inside the desktop app.
   - Any external network access is only through the embedded browser content when the user navigates to a URL.

12. **How to think about the diagram**
   - Draw one central **Electron main process** box connected to:
     - the **primary overlay renderer**
     - the **floating control renderer**
     - **local profile storage**
     - the **OS-level shortcut/event layer**
   - The renderers should not directly touch OS APIs or storage; they communicate upward through preload/IPC.

Main entry points: [`main.js`](https://github.com/fajarnadril/overlaybrowser/blob/main/main.js) (main.js), [`package.json`](https://github.com/fajarnadril/overlaybrowser/blob/main/package.json) (package.json), [`preload.js`](https://github.com/fajarnadril/overlaybrowser/blob/main/preload.js) (preload.js), [`index.html`](https://github.com/fajarnadril/overlaybrowser/blob/main/index.html) (index.html)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_main["Main Process"]
  node_main_js["main.js<br/>electron main<br/>[main.js]"]
  node_os_shortcut(("Global Shortcut<br/>os event"))
  node_ipc_bus{{"IPC Bridge<br/>ipc channel"}}
end

subgraph group_ui["Renderer UIs"]
  node_preload_main["preload.js<br/>renderer bridge<br/>[preload.js]"]
  node_index_html["index.html<br/>overlay shell<br/>[index.html]"]
  node_renderer_js["renderer.js<br/>overlay ui<br/>[renderer.js]"]
  node_float_preload["float-preload.js<br/>control bridge<br/>[float-preload.js]"]
  node_float_html["float-button.html<br/>control shell<br/>[float-button.html]"]
  node_float_renderer["float-renderer.js<br/>control ui<br/>[float-renderer.js]"]
end

subgraph group_state["Local State"]
  node_profile_store["profiles.json<br/>profile schema<br/>[profiles.json]"]
  node_user_data[("User Data<br/>local persistence")]
  node_package_json["package.json<br/>electron build<br/>[package.json]"]
end

node_main_js -->|"registers"| node_os_shortcut
node_os_shortcut -->|"toggles"| node_main_js
node_main_js -->|"routes"| node_ipc_bus
node_renderer_js -->|"uses"| node_preload_main
node_preload_main -->|"invokes"| node_ipc_bus
node_float_renderer -->|"uses"| node_float_preload
node_float_preload -->|"invokes"| node_ipc_bus
node_main_js -->|"creates"| node_index_html
node_index_html -->|"hosts"| node_renderer_js
node_main_js -->|"creates"| node_float_html
node_float_html -->|"hosts"| node_float_renderer
node_main_js -->|"persists"| node_user_data
node_user_data -.->|"shaped by"| node_profile_store
node_package_json -->|"starts"| node_main_js
node_package_json -.->|"packages"| node_user_data

click node_main_js "https://github.com/fajarnadril/overlaybrowser/blob/main/main.js"
click node_preload_main "https://github.com/fajarnadril/overlaybrowser/blob/main/preload.js"
click node_index_html "https://github.com/fajarnadril/overlaybrowser/blob/main/index.html"
click node_renderer_js "https://github.com/fajarnadril/overlaybrowser/blob/main/renderer.js"
click node_float_preload "https://github.com/fajarnadril/overlaybrowser/blob/main/float-preload.js"
click node_float_html "https://github.com/fajarnadril/overlaybrowser/blob/main/float-button.html"
click node_float_renderer "https://github.com/fajarnadril/overlaybrowser/blob/main/float-renderer.js"
click node_profile_store "https://github.com/fajarnadril/overlaybrowser/blob/main/profiles.json"
click node_package_json "https://github.com/fajarnadril/overlaybrowser/blob/main/package.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main_js,node_os_shortcut,node_ipc_bus toneBlue
class node_preload_main,node_index_html,node_renderer_js,node_float_preload,node_float_html,node_float_renderer toneAmber
class node_profile_store,node_user_data,node_package_json toneMint
```

## Components

### Main Process

Electron main process, OS integration, window lifecycle, and IPC coordination.

- [main.js](https://github.com/fajarnadril/overlaybrowser/blob/main/main.js): electron main · Central orchestrator for windows, shortcuts, docking, and persistence. · `main.js`
- **Global Shortcut**: os event · System-level hotkey used to toggle the overlay from anywhere.
- **IPC Bridge**: ipc channel · Command and event path between renderers and the main process.

### Renderer UIs

Browser overlay surface and floating control window.

- [preload.js](https://github.com/fajarnadril/overlaybrowser/blob/main/preload.js): renderer bridge · Security boundary exposing a limited API to the main overlay renderer. · `preload.js`
- [index.html](https://github.com/fajarnadril/overlaybrowser/blob/main/index.html): overlay shell · Primary browser overlay window shell. · `index.html`
- [renderer.js](https://github.com/fajarnadril/overlaybrowser/blob/main/renderer.js): overlay ui · Main overlay UI for navigation and profile actions. · `renderer.js`
- [float-preload.js](https://github.com/fajarnadril/overlaybrowser/blob/main/float-preload.js): control bridge · Secure API bridge for the floating control window. · `float-preload.js`
- [float-button.html](https://github.com/fajarnadril/overlaybrowser/blob/main/float-button.html): control shell · Floating control window shell for docking and window actions. · `float-button.html`
- [float-renderer.js](https://github.com/fajarnadril/overlaybrowser/blob/main/float-renderer.js): control ui · Floating control UI that sends window commands back to main. · `float-renderer.js`

### Local State

Persistent settings and packaged configuration for the desktop app.

- [profiles.json](https://github.com/fajarnadril/overlaybrowser/blob/main/profiles.json): profile schema · Example saved profile structure for URL, dock position, and window state. · `profiles.json`
- **User Data**: local persistence · Electron userData storage used at runtime for persisted app state.
- [package.json](https://github.com/fajarnadril/overlaybrowser/blob/main/package.json): electron build · App manifest and electron-builder packaging configuration. · `package.json`

## Connections

- main.js → Global Shortcut: registers · Main process installs and handles the global hotkey.
- Global Shortcut → main.js: toggles · OS shortcut re-enters the app to show or hide the overlay.
- main.js → IPC Bridge: routes · Main process receives and dispatches renderer commands.
- renderer.js → preload.js: uses · Primary overlay UI calls the exposed preload API.
- preload.js → IPC Bridge: invokes · Preload forwards safe commands to main via IPC.
- float-renderer.js → float-preload.js: uses · Floating control UI calls its preload API.
- float-preload.js → IPC Bridge: invokes · Floating window forwards control commands to main via IPC.
- main.js → index.html: creates · Main process creates the primary overlay window.
- index.html → renderer.js: hosts · HTML shell loads the overlay renderer script.
- main.js → float-button.html: creates · Main process creates the floating control window.
- float-button.html → float-renderer.js: hosts · Floating shell loads the control renderer script.
- main.js → User Data: persists · Main process stores the live app state locally.
- User Data → profiles.json: shaped by · Saved state follows the profile structure documented in the repo.
- package.json → main.js: starts · Electron entrypoint launches the main process.
- package.json → User Data: packages · Build and runtime configuration target a local desktop app.