# zen-browser/desktop architecture

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

- Interactive diagram: https://gitdiagram.com/zen-browser/desktop
- Repository: https://github.com/zen-browser/desktop

## Overview

Zen is a Firefox-based desktop browser focused on productivity. Its principal user workflow is interacting with browser UI to organize spaces and tabs, navigate or route links, and use browsing features such as split view, glance, media, and the library; session and sync modules support continuity. The tree exposes these product areas, but most implementation excerpts do not show their runtime wiring. Dashed edges therefore mark unverified workflow links rather than asserted calls.

Main entry points: [`src/zen/spaces/ZenSpaceManager.mjs`](https://github.com/zen-browser/desktop/blob/dev/src/zen/spaces/ZenSpaceManager.mjs) (Spaces), [`src/zen/common/modules/ZenUIManager.mjs`](https://github.com/zen-browser/desktop/blob/dev/src/zen/common/modules/ZenUIManager.mjs) (UI manager), [`src/zen/space-routing/ZenSpaceRoutingManager.sys.mjs`](https://github.com/zen-browser/desktop/blob/dev/src/zen/space-routing/ZenSpaceRoutingManager.sys.mjs) (Space routing), [`src/zen/sync/ZenSpacesSync.sys.mjs`](https://github.com/zen-browser/desktop/blob/dev/src/zen/sync/ZenSpacesSync.sys.mjs) (Spaces sync)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Browser UI"]
  node_ui_manager["UI manager<br/>[ZenUIManager.mjs]"]
  node_settings["Preferences<br/>[zen-settings.js]"]
  node_compact["Compact mode<br/>[ZenCompactMode.mjs]"]
  node_shortcuts["Keyboard shortcuts"]
end

subgraph group_organization["Spaces And Tabs"]
  node_spaces["Spaces"]
  node_space_creation["Space creation"]
  node_folders["Folders<br/>[ZenFolders.mjs]"]
  node_pinned_tabs["Pinned tabs"]
  node_split_view["Split view"]
end

subgraph group_navigation["Navigation Features"]
  node_space_routing["Space routing"]
  node_routing_dialog["Routing dialog"]
  node_glance["Glance"]
  node_urlbar["URL bar actions"]
end

subgraph group_browsing["Browsing Tools"]
  node_library["Library<br/>[ZenLibrary.mjs]"]
  node_live_folders["Live folders"]
  node_media["Media controls"]
  node_boosts["Boosts"]
end

subgraph group_continuity["State And Sync"]
  node_session["Session manager"]
  node_space_storage["Space bookmarks"]
  node_sync["Spaces sync"]
end

node_user(("Browser user"))

node_user -.->|"uses"| node_ui_manager
node_user -.->|"configures"| node_settings
node_user -.->|"organizes"| node_spaces
node_user -.->|"routes links"| node_space_routing
node_user -.->|"browses library"| node_library
node_user -.->|"uses"| node_split_view
node_spaces -.->|"supports"| node_space_creation
node_spaces -.->|"organizes"| node_folders
node_spaces -.->|"organizes"| node_pinned_tabs
node_spaces -.->|"persists"| node_space_storage
node_spaces -.->|"syncs"| node_sync
node_space_routing -.->|"presents"| node_routing_dialog
node_ui_manager -.->|"coordinates"| node_compact
node_ui_manager -.->|"coordinates"| node_shortcuts
node_session -.->|"preserves state"| node_sync

click node_ui_manager "https://github.com/zen-browser/desktop/blob/dev/src/zen/common/modules/ZenUIManager.mjs"
click node_settings "https://github.com/zen-browser/desktop/blob/dev/src/browser/components/preferences/zen-settings.js"
click node_compact "https://github.com/zen-browser/desktop/blob/dev/src/zen/compact-mode/ZenCompactMode.mjs"
click node_shortcuts "https://github.com/zen-browser/desktop/blob/dev/src/zen/kbs/ZenKeyboardShortcuts.mjs"
click node_spaces "https://github.com/zen-browser/desktop/blob/dev/src/zen/spaces/ZenSpaceManager.mjs"
click node_space_creation "https://github.com/zen-browser/desktop/blob/dev/src/zen/spaces/ZenSpaceCreation.mjs"
click node_folders "https://github.com/zen-browser/desktop/blob/dev/src/zen/folders/ZenFolders.mjs"
click node_pinned_tabs "https://github.com/zen-browser/desktop/blob/dev/src/zen/tabs/ZenPinnedTabManager.mjs"
click node_split_view "https://github.com/zen-browser/desktop/blob/dev/src/zen/split-view/ZenViewSplitter.mjs"
click node_space_routing "https://github.com/zen-browser/desktop/blob/dev/src/zen/space-routing/ZenSpaceRoutingManager.sys.mjs"
click node_routing_dialog "https://github.com/zen-browser/desktop/blob/dev/src/zen/space-routing/ZenSpaceRoutingDialog.mjs"
click node_glance "https://github.com/zen-browser/desktop/blob/dev/src/zen/glance/ZenGlanceManager.mjs"
click node_urlbar "https://github.com/zen-browser/desktop/blob/dev/src/zen/urlbar/ZenUBActionsProvider.sys.mjs"
click node_library "https://github.com/zen-browser/desktop/blob/dev/src/zen/library/ZenLibrary.mjs"
click node_live_folders "https://github.com/zen-browser/desktop/blob/dev/src/zen/live-folders/ZenLiveFoldersManager.sys.mjs"
click node_media "https://github.com/zen-browser/desktop/blob/dev/src/zen/media/ZenMediaController.mjs"
click node_boosts "https://github.com/zen-browser/desktop/blob/dev/src/zen/boosts/ZenBoostsManager.sys.mjs"
click node_session "https://github.com/zen-browser/desktop/blob/dev/src/zen/sessionstore/ZenSessionManager.sys.mjs"
click node_space_storage "https://github.com/zen-browser/desktop/blob/dev/src/zen/spaces/ZenSpaceBookmarksStorage.js"
click node_sync "https://github.com/zen-browser/desktop/blob/dev/src/zen/sync/ZenSpacesSync.sys.mjs"

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_ui_manager,node_settings,node_compact,node_shortcuts,node_user toneBlue
class node_spaces,node_space_creation,node_folders,node_pinned_tabs,node_split_view toneAmber
class node_space_routing,node_routing_dialog,node_glance,node_urlbar toneMint
class node_library,node_live_folders,node_media,node_boosts toneRose
class node_session,node_space_storage,node_sync toneIndigo
```

## Components

### Browser UI

- [UI manager](https://github.com/zen-browser/desktop/blob/dev/src/zen/common/modules/ZenUIManager.mjs): `src/zen/common/modules/ZenUIManager.mjs`
- [Preferences](https://github.com/zen-browser/desktop/blob/dev/src/browser/components/preferences/zen-settings.js): `src/browser/components/preferences/zen-settings.js`
- [Compact mode](https://github.com/zen-browser/desktop/blob/dev/src/zen/compact-mode/ZenCompactMode.mjs): `src/zen/compact-mode/ZenCompactMode.mjs`
- [Keyboard shortcuts](https://github.com/zen-browser/desktop/blob/dev/src/zen/kbs/ZenKeyboardShortcuts.mjs): `src/zen/kbs/ZenKeyboardShortcuts.mjs`

### Spaces And Tabs

- [Spaces](https://github.com/zen-browser/desktop/blob/dev/src/zen/spaces/ZenSpaceManager.mjs): `src/zen/spaces/ZenSpaceManager.mjs`
- [Space creation](https://github.com/zen-browser/desktop/blob/dev/src/zen/spaces/ZenSpaceCreation.mjs): `src/zen/spaces/ZenSpaceCreation.mjs`
- [Folders](https://github.com/zen-browser/desktop/blob/dev/src/zen/folders/ZenFolders.mjs): `src/zen/folders/ZenFolders.mjs`
- [Pinned tabs](https://github.com/zen-browser/desktop/blob/dev/src/zen/tabs/ZenPinnedTabManager.mjs): `src/zen/tabs/ZenPinnedTabManager.mjs`
- [Split view](https://github.com/zen-browser/desktop/blob/dev/src/zen/split-view/ZenViewSplitter.mjs): `src/zen/split-view/ZenViewSplitter.mjs`

### Navigation Features

- [Space routing](https://github.com/zen-browser/desktop/blob/dev/src/zen/space-routing/ZenSpaceRoutingManager.sys.mjs): `src/zen/space-routing/ZenSpaceRoutingManager.sys.mjs`
- [Routing dialog](https://github.com/zen-browser/desktop/blob/dev/src/zen/space-routing/ZenSpaceRoutingDialog.mjs): `src/zen/space-routing/ZenSpaceRoutingDialog.mjs`
- [Glance](https://github.com/zen-browser/desktop/blob/dev/src/zen/glance/ZenGlanceManager.mjs): `src/zen/glance/ZenGlanceManager.mjs`
- [URL bar actions](https://github.com/zen-browser/desktop/blob/dev/src/zen/urlbar/ZenUBActionsProvider.sys.mjs): `src/zen/urlbar/ZenUBActionsProvider.sys.mjs`

### Browsing Tools

- [Library](https://github.com/zen-browser/desktop/blob/dev/src/zen/library/ZenLibrary.mjs): `src/zen/library/ZenLibrary.mjs`
- [Live folders](https://github.com/zen-browser/desktop/blob/dev/src/zen/live-folders/ZenLiveFoldersManager.sys.mjs): `src/zen/live-folders/ZenLiveFoldersManager.sys.mjs`
- [Media controls](https://github.com/zen-browser/desktop/blob/dev/src/zen/media/ZenMediaController.mjs): `src/zen/media/ZenMediaController.mjs`
- [Boosts](https://github.com/zen-browser/desktop/blob/dev/src/zen/boosts/ZenBoostsManager.sys.mjs): `src/zen/boosts/ZenBoostsManager.sys.mjs`

### State And Sync

- [Session manager](https://github.com/zen-browser/desktop/blob/dev/src/zen/sessionstore/ZenSessionManager.sys.mjs): `src/zen/sessionstore/ZenSessionManager.sys.mjs`
- [Space bookmarks](https://github.com/zen-browser/desktop/blob/dev/src/zen/spaces/ZenSpaceBookmarksStorage.js): `src/zen/spaces/ZenSpaceBookmarksStorage.js`
- [Spaces sync](https://github.com/zen-browser/desktop/blob/dev/src/zen/sync/ZenSpacesSync.sys.mjs): `src/zen/sync/ZenSpacesSync.sys.mjs`

### Other components

- **Browser user**

## Connections

- Browser user → UI manager: uses
- Browser user → Preferences: configures
- Browser user → Spaces: organizes
- Browser user → Space routing: routes links
- Browser user → Library: browses library
- Browser user → Split view: uses
- Spaces → Space creation: supports
- Spaces → Folders: organizes
- Spaces → Pinned tabs: organizes
- Spaces → Space bookmarks: persists
- Spaces → Spaces sync: syncs
- Space routing → Routing dialog: presents
- UI manager → Compact mode: coordinates
- UI manager → Keyboard shortcuts: coordinates
- Session manager → Spaces sync: preserves state
