--- title: Architecture description: How Freedom Browser is put together: Electron main and renderer processes, protocol handlers, embedded nodes, the page providers and the security model. kick: Contribute dek: An Electron app whose main process owns protocols, nodes, permissions and the wallet. The renderer is UI, and pages only reach privileged features through narrow providers. source: https://github.com/solardev-xyz/freedom-browser/blob/main/README.md#architecture --- ## Processes | Layer | Directory | Owns | | ----- | --------- | ---- | | Main process | [`src/main/`](https://github.com/solardev-xyz/freedom-browser/tree/main/src/main) | Protocol handlers, per-profile node lifecycles, permissions, wallet, downloads, updates, persistence | | Renderer | [`src/renderer/`](https://github.com/solardev-xyz/freedom-browser/tree/main/src/renderer) | Browser UI: tabs, navigation, menus, settings, internal `freedom://` pages, dapp integration and consent prompts | | Shared | [`src/shared/`](https://github.com/solardev-xyz/freedom-browser/tree/main/src/shared) | Constants and utilities used by both, including the IPC channel allowlist | The renderer talks to the main process only through the allowlisted channels in [`src/shared/ipc-channels.js`](https://github.com/solardev-xyz/freedom-browser/blob/main/src/shared/ipc-channels.js). Protocol and privileged logic belongs in the main process. Before you move responsibilities between processes or add an IPC channel, read the [architecture boundaries playbook](https://github.com/solardev-xyz/freedom-browser/blob/main/docs/agent-playbooks/architecture-boundaries.md); changes to those boundaries need maintainer approval. Other top-level directories: `test-e2e/` (Playwright), `config/` (runtime templates, default data, entitlements), `scripts/` (build, download, smoke-test tooling), `assets/` (icons) and `docs/`. ## Protocols and nodes The main process handles `bzz:`, `ipfs:`, `ipns:`, `web3:`, `rad:` and `.onion` navigation, runs each profile's nodes, and resolves decentralized names. - **Swarm** runs on Ant (`antd`), a node that speaks the Bee HTTP API. Its wire and identity contract (endpoints, port 1633, config keys, key files) deliberately keeps Bee's names; the playbook lists what must not be renamed. - **IPFS** uses the freedom-ipfs native addon. - **Radicle** runs in-process through the embedded libradicle addon. No CLI, HTTP daemon or local port is involved, and `rad:` URLs are served from the node's storage. - **`web3:`** needs no node: the handler reads a contract's ERC-8244 `html()` document through the chain-data router the wallet uses. - **Tor** is an optional Arti binary for `.onion` sites. ## Page providers `window.swarm`, `window.radicle` and `window.ethereum` are installed in the main world of every web page's top frame before the page's own scripts run. A request travels through three places: | Step | Files | | ---- | ----- | | Page shim (injected) | [`src/main/webview-preload.js`](https://github.com/solardev-xyz/freedom-browser/blob/main/src/main/webview-preload.js) | | Consent prompts and UX | [`src/renderer/lib/swarm-provider.js`](https://github.com/solardev-xyz/freedom-browser/blob/main/src/renderer/lib/swarm-provider.js), [`src/renderer/lib/radicle-provider.js`](https://github.com/solardev-xyz/freedom-browser/blob/main/src/renderer/lib/radicle-provider.js) | | Authority: grants, validation, node calls | [`src/main/swarm/swarm-provider-ipc.js`](https://github.com/solardev-xyz/freedom-browser/blob/main/src/main/swarm/swarm-provider-ipc.js), [`src/main/radicle/radicle-provider-ipc.js`](https://github.com/solardev-xyz/freedom-browser/blob/main/src/main/radicle/radicle-provider-ipc.js) | The main process re-checks every grant; the renderer's prompts are UX, not the security boundary. Grants are keyed by the address-bar origin, which the main process derives itself. Requests from pages to the local node API on port 1633 are blocked, so pages reach the node only through the provider. ## Security model - Context isolation is on and Node integration is off in web content. - Privileged internal APIs are limited to trusted `freedom://` pages or the narrow provider surfaces above. - Web permissions are denied by default and granted through per-site prompts. - Nodes run locally by default; external endpoints are explicit per-profile settings. File security findings publicly on GitHub; see [Community](community.html.md#security).