# driceroland/search architecture

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

- Interactive diagram: https://gitdiagram.com/driceroland/search
- Repository: https://github.com/driceroland/search
- Video tour (about a minute): https://gitdiagram.com/driceroland/search/video

## Overview

Search is a lightweight macOS WebKit browser. The main workflow is entering an address or search in the browser field, opening it in a tab, and displaying the page; the browser also manages local browsing state and built-in privacy and convenience features. The README documents major capabilities not visible in the sampled excerpts, so those are represented at subsystem level using their exact source paths. Some internal wiring is omitted where excerpts do not establish the caller.

Main entry points: [`Sources/Search/Browser.swift`](https://github.com/driceroland/search/blob/main/Sources/Search/Browser.swift) (Browser coordinator), [`Sources/Search/Extensions.swift`](https://github.com/driceroland/search/blob/main/Sources/Search/Extensions.swift) (Extension manager), [`Sources/Search/Tab.swift`](https://github.com/driceroland/search/blob/main/Sources/Search/Tab.swift) (Tab and page), [`Sources/Search/App.swift`](https://github.com/driceroland/search/blob/main/Sources/Search/App.swift) (Window and commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Window and controls"]
  node_app["Window and commands<br/>[App.swift]"]
  node_tabui["Tab layout<br/>[TabBar.swift]"]
end

subgraph group_browsing["Pages and tabs"]
  node_browser["Browser coordinator<br/>[Browser.swift]"]
  node_address["Address handling<br/>[Address.swift]"]
  node_omnibox["Search field<br/>[Omnibox.swift]"]
  node_engine["Search providers<br/>[Engine.swift]"]
  node_tabs["Tab and page<br/>[Tab.swift]"]
  node_reader["Reading mode<br/>[Reader.swift]"]
  node_float["Floating video<br/>[Float.swift]"]
end

subgraph group_privacy["Privacy and identity"]
  node_shield["Network blocker<br/>[Shield.swift]"]
  node_hidden["Hidden elements<br/>[Hidden.swift]"]
  node_accounts["Saved accounts<br/>[Accounts.swift]"]
  node_vault["Password vault<br/>[Vault.swift]"]
  node_passkeys["Passkeys<br/>[Passkeys.swift]"]
end

subgraph group_local["Local browser data"]
  node_bookmarks["Bookmarks<br/>[Bookmarks.swift]"]
  node_history["History<br/>[History.swift]"]
  node_session["Session restore<br/>[Session.swift]"]
  node_store[("Local JSON store<br/>[Store.swift]")]
  node_updater["Quiet updater<br/>[Updater.swift]"]
end

subgraph group_extensions["Extension support"]
  node_extensions["Extension manager<br/>[Extensions.swift]"]
  node_crx["CRX installer<br/>[Crx.swift]"]
  node_shims["Chrome API shims"]
  node_native["Native extension APIs"]
end

node_user(("User"))
node_webkit["WebKit engine"]
node_websites(("Web pages"))
node_keychain[("macOS keychain")]
node_webext["WebKit extensions"]
node_extensionstore[("Extension data store")]
node_update(("Update service"))

node_user -->|"uses"| node_app
node_app -->|"commands"| node_browser
node_app -->|"displays"| node_tabui
node_browser -->|"reads input"| node_omnibox
node_omnibox -->|"resolves"| node_address
node_omnibox -->|"builds search"| node_engine
node_browser -->|"opens pages"| node_tabs
node_tabs -->|"hosts page"| node_webkit
node_webkit -->|"loads"| node_websites
node_reader -->|"transforms page"| node_tabs
node_shield -->|"blocks requests"| node_webkit
node_hidden -->|"injects selectors"| node_webkit
node_float -->|"floats video"| node_tabs
node_accounts -->|"offers credentials"| node_vault
node_vault -->|"reads and writes"| node_keychain
node_passkeys -->|"handles credentials"| node_webkit
node_bookmarks -->|"persists"| node_store
node_history -->|"persists"| node_store
node_session -->|"reads and writes"| node_store
node_browser -->|"manages"| node_bookmarks
node_browser -->|"records visits"| node_history
node_browser -->|"restores tabs"| node_session
node_browser -->|"configures"| node_shield
node_browser -->|"starts manager"| node_extensions
node_extensions -->|"installs package"| node_crx
node_extensions -->|"registers extensions"| node_webext
node_extensions -->|"prepares scripts"| node_shims
node_shims -->|"dispatches API calls"| node_native
node_webext -->|"stores extension data"| node_extensionstore
node_browser -.->|"checks updates"| node_updater
node_updater -.->|"checks and downloads"| node_update

click node_app "https://github.com/driceroland/search/blob/main/Sources/Search/App.swift"
click node_browser "https://github.com/driceroland/search/blob/main/Sources/Search/Browser.swift"
click node_address "https://github.com/driceroland/search/blob/main/Sources/Search/Address.swift"
click node_omnibox "https://github.com/driceroland/search/blob/main/Sources/Search/Omnibox.swift"
click node_engine "https://github.com/driceroland/search/blob/main/Sources/Search/Engine.swift"
click node_tabs "https://github.com/driceroland/search/blob/main/Sources/Search/Tab.swift"
click node_tabui "https://github.com/driceroland/search/blob/main/Sources/Search/TabBar.swift"
click node_reader "https://github.com/driceroland/search/blob/main/Sources/Search/Reader.swift"
click node_shield "https://github.com/driceroland/search/blob/main/Sources/Search/Shield.swift"
click node_hidden "https://github.com/driceroland/search/blob/main/Sources/Search/Hidden.swift"
click node_float "https://github.com/driceroland/search/blob/main/Sources/Search/Float.swift"
click node_accounts "https://github.com/driceroland/search/blob/main/Sources/Search/Accounts.swift"
click node_vault "https://github.com/driceroland/search/blob/main/Sources/Search/Vault.swift"
click node_passkeys "https://github.com/driceroland/search/blob/main/Sources/Search/Passkeys.swift"
click node_bookmarks "https://github.com/driceroland/search/blob/main/Sources/Search/Bookmarks.swift"
click node_history "https://github.com/driceroland/search/blob/main/Sources/Search/History.swift"
click node_session "https://github.com/driceroland/search/blob/main/Sources/Search/Session.swift"
click node_store "https://github.com/driceroland/search/blob/main/Sources/Search/Store.swift"
click node_extensions "https://github.com/driceroland/search/blob/main/Sources/Search/Extensions.swift"
click node_crx "https://github.com/driceroland/search/blob/main/Sources/Search/Crx.swift"
click node_shims "https://github.com/driceroland/search/blob/main/Sources/Search/ExtensionShims.swift"
click node_native "https://github.com/driceroland/search/blob/main/Sources/Search/ExtensionNative.swift"
click node_updater "https://github.com/driceroland/search/blob/main/Sources/Search/Updater.swift"

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_app,node_tabui,node_user toneBlue
class node_browser,node_address,node_omnibox,node_engine,node_tabs,node_reader,node_float,node_keychain,node_extensionstore toneAmber
class node_shield,node_hidden,node_accounts,node_vault,node_passkeys toneMint
class node_bookmarks,node_history,node_session,node_store,node_updater toneRose
class node_extensions,node_crx,node_shims,node_native,node_webkit,node_websites,node_webext,node_update toneIndigo
```

## Components

### Window and controls

- [Window and commands](https://github.com/driceroland/search/blob/main/Sources/Search/App.swift): `Sources/Search/App.swift`
- [Tab layout](https://github.com/driceroland/search/blob/main/Sources/Search/TabBar.swift): `Sources/Search/TabBar.swift`

### Pages and tabs

- [Browser coordinator](https://github.com/driceroland/search/blob/main/Sources/Search/Browser.swift): `Sources/Search/Browser.swift`
- [Address handling](https://github.com/driceroland/search/blob/main/Sources/Search/Address.swift): `Sources/Search/Address.swift`
- [Search field](https://github.com/driceroland/search/blob/main/Sources/Search/Omnibox.swift): `Sources/Search/Omnibox.swift`
- [Search providers](https://github.com/driceroland/search/blob/main/Sources/Search/Engine.swift): `Sources/Search/Engine.swift`
- [Tab and page](https://github.com/driceroland/search/blob/main/Sources/Search/Tab.swift): `Sources/Search/Tab.swift`
- [Reading mode](https://github.com/driceroland/search/blob/main/Sources/Search/Reader.swift): `Sources/Search/Reader.swift`
- [Floating video](https://github.com/driceroland/search/blob/main/Sources/Search/Float.swift): `Sources/Search/Float.swift`

### Privacy and identity

- [Network blocker](https://github.com/driceroland/search/blob/main/Sources/Search/Shield.swift): `Sources/Search/Shield.swift`
- [Hidden elements](https://github.com/driceroland/search/blob/main/Sources/Search/Hidden.swift): `Sources/Search/Hidden.swift`
- [Saved accounts](https://github.com/driceroland/search/blob/main/Sources/Search/Accounts.swift): `Sources/Search/Accounts.swift`
- [Password vault](https://github.com/driceroland/search/blob/main/Sources/Search/Vault.swift): `Sources/Search/Vault.swift`
- [Passkeys](https://github.com/driceroland/search/blob/main/Sources/Search/Passkeys.swift): `Sources/Search/Passkeys.swift`

### Local browser data

- [Bookmarks](https://github.com/driceroland/search/blob/main/Sources/Search/Bookmarks.swift): `Sources/Search/Bookmarks.swift`
- [History](https://github.com/driceroland/search/blob/main/Sources/Search/History.swift): `Sources/Search/History.swift`
- [Session restore](https://github.com/driceroland/search/blob/main/Sources/Search/Session.swift): `Sources/Search/Session.swift`
- [Local JSON store](https://github.com/driceroland/search/blob/main/Sources/Search/Store.swift): `Sources/Search/Store.swift`
- [Quiet updater](https://github.com/driceroland/search/blob/main/Sources/Search/Updater.swift): `Sources/Search/Updater.swift`

### Extension support

- [Extension manager](https://github.com/driceroland/search/blob/main/Sources/Search/Extensions.swift): `Sources/Search/Extensions.swift`
- [CRX installer](https://github.com/driceroland/search/blob/main/Sources/Search/Crx.swift): `Sources/Search/Crx.swift`
- [Chrome API shims](https://github.com/driceroland/search/blob/main/Sources/Search/ExtensionShims.swift): `Sources/Search/ExtensionShims.swift`
- [Native extension APIs](https://github.com/driceroland/search/blob/main/Sources/Search/ExtensionNative.swift): `Sources/Search/ExtensionNative.swift`

### Other components

- **User**
- **WebKit engine**
- **Web pages**
- **macOS keychain**
- **WebKit extensions**
- **Extension data store**
- **Update service**

## Connections

- User → Window and commands: uses
- Window and commands → Browser coordinator: commands
- Window and commands → Tab layout: displays
- Browser coordinator → Search field: reads input
- Search field → Address handling: resolves
- Search field → Search providers: builds search
- Browser coordinator → Tab and page: opens pages
- Tab and page → WebKit engine: hosts page
- WebKit engine → Web pages: loads
- Reading mode → Tab and page: transforms page
- Network blocker → WebKit engine: blocks requests
- Hidden elements → WebKit engine: injects selectors
- Floating video → Tab and page: floats video
- Saved accounts → Password vault: offers credentials
- Password vault → macOS keychain: reads and writes
- Passkeys → WebKit engine: handles credentials
- Bookmarks → Local JSON store: persists
- History → Local JSON store: persists
- Session restore → Local JSON store: reads and writes
- Browser coordinator → Bookmarks: manages
- Browser coordinator → History: records visits
- Browser coordinator → Session restore: restores tabs
- Browser coordinator → Network blocker: configures
- Browser coordinator → Extension manager: starts manager
- Extension manager → CRX installer: installs package
- Extension manager → WebKit extensions: registers extensions
- Extension manager → Chrome API shims: prepares scripts
- Chrome API shims → Native extension APIs: dispatches API calls
- WebKit extensions → Extension data store: stores extension data
- Browser coordinator → Quiet updater: checks updates
- Quiet updater → Update service: checks and downloads