How fajarnadril/overlaybrowser works
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 main.js · package.json package.json · preload.js preload.js · index.html index.html
Components 12
Main Process
Electron main process, OS integration, window lifecycle, and IPC coordination.
- main.js · Central orchestrator for windows, shortcuts, docking, and persistence.
main.js - Global Shortcut · System-level hotkey used to toggle the overlay from anywhere.
- IPC Bridge · Command and event path between renderers and the main process.
Renderer UIs
Browser overlay surface and floating control window.
- preload.js · Security boundary exposing a limited API to the main overlay renderer.
preload.js - index.html · Primary browser overlay window shell.
index.html - renderer.js · Main overlay UI for navigation and profile actions.
renderer.js - float-preload.js · Secure API bridge for the floating control window.
float-preload.js - float-button.html · Floating control window shell for docking and window actions.
float-button.html - float-renderer.js · 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 · Example saved profile structure for URL, dock position, and window state.
profiles.json - User Data · Electron userData storage used at runtime for persisted app state.
- package.json · App manifest and electron-builder packaging configuration.
package.json
Connections 15
- 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.