# irmak-b/browser-v0.1 architecture

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

- Interactive diagram: https://gitdiagram.com/irmak-b/browser-v0.1
- Repository: https://github.com/irmak-b/browser-v0.1

## Overview

Browser Core is an Electron desktop browser: the user enters an address or search, the trusted UI sends commands to the main process, and main-owned browser state manages isolated site contents, navigation, permissions, filtering, and results. The graph includes documented tab, popup, download, history, page-tool, and resource-management capabilities, plus the character/theme UI branch. Several source excerpts are partial, so edges are limited to shown references or README statements; unsampled behavior is not inferred.

Main entry points: [`src/main/browser/tab-manager.ts`](https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/tab-manager.ts) (Tab manager), [`src/main/browser/controller.ts`](https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/controller.ts) (Browser controller), [`src/main/browser/site-sessions.ts`](https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/site-sessions.ts) (Site contents), [`src/renderer/theme/ThemeProvider.tsx`](https://github.com/irmak-b/browser-v0.1/blob/main/src/renderer/theme/ThemeProvider.tsx) (Theme provider)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interface"]
  node_devui["Browser UI<br/>[main.tsx]"]
  node_preload["Preload API<br/>[index.ts]"]
  node_contracts["Shared contracts<br/>[contracts.ts]"]
end

subgraph group_runtime["Browser Runtime"]
  node_main["Electron startup<br/>[index.ts]"]
  node_ipc["Command IPC<br/>[ipc.ts]"]
  node_controller["Browser controller<br/>[controller.ts]"]
  node_tabs["Tab manager<br/>[tab-manager.ts]"]
  node_sitecontents["Site contents<br/>[site-sessions.ts]"]
end

subgraph group_protection["Site Controls"]
  node_policy["Address policy<br/>[policy.ts]"]
  node_permissions["Permission policy"]
  node_sitepermissions["Site permissions"]
  node_resourcepolicy["Resource policy<br/>[resource-policy.ts]"]
  node_popup["Popup policy<br/>[popup-policy.ts]"]
  node_adblocker["Ad blocker<br/>[ad-blocker.ts]"]
  node_filterengine["Filter engine"]
  node_scriptlets["Ad scriptlets<br/>[ad-scriptlets.ts]"]
end

subgraph group_support["Browser Services"]
  node_downloads["Download manager<br/>[downloads.ts]"]
  node_history["History service<br/>[history.ts]"]
  node_closedtabs["Closed tabs<br/>[closed-tabs.ts]"]
  node_freezer["Page freezer<br/>[page-freezer.ts]"]
  node_workers["Idle workers<br/>[idle-workers.ts]"]
  node_rendererwatchdog["Renderer watchdog"]
end

subgraph group_appearance["Character Theme"]
  node_themeprovider["Theme provider<br/>[ThemeProvider.tsx]"]
  node_profilestore["Character profile<br/>[profileStore.ts]"]
  node_themes["Theme definitions<br/>[themes.ts]"]
  node_character["Character types<br/>[character.ts]"]
end

node_user(("Browser user"))
node_web(("Web destinations"))

node_user -->|"enters address"| node_devui
node_devui -.->|"uses browser API"| node_preload
node_main -->|"creates"| node_controller
node_main -->|"registers"| node_ipc
node_main -->|"loads UI"| node_devui
node_ipc -->|"dispatches commands"| node_controller
node_controller -->|"resolves input"| node_policy
node_controller -->|"delegates tab actions"| node_tabs
node_controller -->|"creates sessions"| node_sitecontents
node_controller -->|"manages downloads"| node_downloads
node_tabs -->|"navigates pages"| node_web
node_tabs -->|"checks popup intent"| node_popup
node_tabs -->|"restores tabs"| node_closedtabs
node_tabs -->|"uses page freezer"| node_freezer
node_tabs -->|"checks health"| node_rendererwatchdog
node_sitecontents -->|"denies permissions"| node_permissions
node_sitecontents -->|"checks scripts"| node_resourcepolicy
node_sitecontents -->|"creates filter"| node_adblocker
node_sitecontents -->|"uses permissions"| node_sitepermissions
node_sitecontents -->|"manages workers"| node_workers
node_adblocker -->|"uses engine"| node_filterengine
node_adblocker -->|"uses scriptlets"| node_scriptlets
node_devui -->|"renders within"| node_themeprovider
node_themeprovider -->|"loads and saves"| node_profilestore
node_themeprovider -->|"selects theme"| node_themes
node_themeprovider -->|"uses profile types"| node_character
node_profilestore -->|"stores profile"| node_character
node_controller -->|"uses history"| node_history
node_tabs -->|"uses resource policy"| node_resourcepolicy

click node_devui "https://github.com/irmak-b/browser-v0.1/blob/main/src/renderer/dev/main.tsx"
click node_preload "https://github.com/irmak-b/browser-v0.1/blob/main/src/preload/index.ts"
click node_contracts "https://github.com/irmak-b/browser-v0.1/blob/main/src/shared/contracts.ts"
click node_main "https://github.com/irmak-b/browser-v0.1/blob/main/src/main/index.ts"
click node_ipc "https://github.com/irmak-b/browser-v0.1/blob/main/src/main/ipc.ts"
click node_controller "https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/controller.ts"
click node_tabs "https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/tab-manager.ts"
click node_sitecontents "https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/site-sessions.ts"
click node_policy "https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/policy.ts"
click node_permissions "https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/permission-policy.ts"
click node_sitepermissions "https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/site-permissions.ts"
click node_resourcepolicy "https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/resource-policy.ts"
click node_popup "https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/popup-policy.ts"
click node_adblocker "https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/ad-blocker.ts"
click node_filterengine "https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/ad-filter-engine.ts"
click node_scriptlets "https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/ad-scriptlets.ts"
click node_downloads "https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/downloads.ts"
click node_history "https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/history.ts"
click node_closedtabs "https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/closed-tabs.ts"
click node_freezer "https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/page-freezer.ts"
click node_workers "https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/idle-workers.ts"
click node_rendererwatchdog "https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/renderer-watchdog.ts"
click node_themeprovider "https://github.com/irmak-b/browser-v0.1/blob/main/src/renderer/theme/ThemeProvider.tsx"
click node_profilestore "https://github.com/irmak-b/browser-v0.1/blob/main/src/renderer/onboarding/profileStore.ts"
click node_themes "https://github.com/irmak-b/browser-v0.1/blob/main/src/renderer/theme/themes.ts"
click node_character "https://github.com/irmak-b/browser-v0.1/blob/main/src/shared/character.ts"

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_devui,node_preload,node_contracts,node_user toneBlue
class node_main,node_ipc,node_controller,node_tabs,node_sitecontents toneAmber
class node_policy,node_permissions,node_sitepermissions,node_resourcepolicy,node_popup,node_adblocker,node_filterengine,node_scriptlets toneMint
class node_downloads,node_history,node_closedtabs,node_freezer,node_workers,node_rendererwatchdog toneRose
class node_themeprovider,node_profilestore,node_themes,node_character,node_web toneIndigo
```

## Components

### User Interface

- [Browser UI](https://github.com/irmak-b/browser-v0.1/blob/main/src/renderer/dev/main.tsx): `src/renderer/dev/main.tsx`
- [Preload API](https://github.com/irmak-b/browser-v0.1/blob/main/src/preload/index.ts): `src/preload/index.ts`
- [Shared contracts](https://github.com/irmak-b/browser-v0.1/blob/main/src/shared/contracts.ts): `src/shared/contracts.ts`

### Browser Runtime

- [Electron startup](https://github.com/irmak-b/browser-v0.1/blob/main/src/main/index.ts): `src/main/index.ts`
- [Command IPC](https://github.com/irmak-b/browser-v0.1/blob/main/src/main/ipc.ts): `src/main/ipc.ts`
- [Browser controller](https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/controller.ts): `src/main/browser/controller.ts`
- [Tab manager](https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/tab-manager.ts): `src/main/browser/tab-manager.ts`
- [Site contents](https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/site-sessions.ts): `src/main/browser/site-sessions.ts`

### Site Controls

- [Address policy](https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/policy.ts): `src/main/browser/policy.ts`
- [Permission policy](https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/permission-policy.ts): `src/main/browser/permission-policy.ts`
- [Site permissions](https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/site-permissions.ts): `src/main/browser/site-permissions.ts`
- [Resource policy](https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/resource-policy.ts): `src/main/browser/resource-policy.ts`
- [Popup policy](https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/popup-policy.ts): `src/main/browser/popup-policy.ts`
- [Ad blocker](https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/ad-blocker.ts): `src/main/browser/ad-blocker.ts`
- [Filter engine](https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/ad-filter-engine.ts): `src/main/browser/ad-filter-engine.ts`
- [Ad scriptlets](https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/ad-scriptlets.ts): `src/main/browser/ad-scriptlets.ts`

### Browser Services

- [Download manager](https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/downloads.ts): `src/main/browser/downloads.ts`
- [History service](https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/history.ts): `src/main/browser/history.ts`
- [Closed tabs](https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/closed-tabs.ts): `src/main/browser/closed-tabs.ts`
- [Page freezer](https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/page-freezer.ts): `src/main/browser/page-freezer.ts`
- [Idle workers](https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/idle-workers.ts): `src/main/browser/idle-workers.ts`
- [Renderer watchdog](https://github.com/irmak-b/browser-v0.1/blob/main/src/main/browser/renderer-watchdog.ts): `src/main/browser/renderer-watchdog.ts`

### Character Theme

- [Theme provider](https://github.com/irmak-b/browser-v0.1/blob/main/src/renderer/theme/ThemeProvider.tsx): `src/renderer/theme/ThemeProvider.tsx`
- [Character profile](https://github.com/irmak-b/browser-v0.1/blob/main/src/renderer/onboarding/profileStore.ts): `src/renderer/onboarding/profileStore.ts`
- [Theme definitions](https://github.com/irmak-b/browser-v0.1/blob/main/src/renderer/theme/themes.ts): `src/renderer/theme/themes.ts`
- [Character types](https://github.com/irmak-b/browser-v0.1/blob/main/src/shared/character.ts): `src/shared/character.ts`

### Other components

- **Browser user**
- **Web destinations**

## Connections

- Browser user → Browser UI: enters address (evidence: `README.md`)
- Browser UI → Preload API: uses browser API
- Electron startup → Browser controller: creates (evidence: `src/main/index.ts`)
- Electron startup → Command IPC: registers (evidence: `src/main/index.ts`)
- Electron startup → Browser UI: loads UI (evidence: `src/main/index.ts`)
- Command IPC → Browser controller: dispatches commands (evidence: `src/main/ipc.ts`)
- Browser controller → Address policy: resolves input (evidence: `src/main/browser/controller.ts`)
- Browser controller → Tab manager: delegates tab actions (evidence: `src/main/browser/controller.ts`)
- Browser controller → Site contents: creates sessions (evidence: `src/main/browser/controller.ts`)
- Browser controller → Download manager: manages downloads (evidence: `src/main/browser/controller.ts`)
- Tab manager → Web destinations: navigates pages (evidence: `README.md`)
- Tab manager → Popup policy: checks popup intent (evidence: `src/main/browser/tab-manager.ts`)
- Tab manager → Closed tabs: restores tabs (evidence: `src/main/browser/tab-manager.ts`)
- Tab manager → Page freezer: uses page freezer (evidence: `src/main/browser/tab-manager.ts`)
- Tab manager → Renderer watchdog: checks health (evidence: `src/main/browser/tab-manager.ts`)
- Site contents → Permission policy: denies permissions (evidence: `src/main/browser/site-sessions.ts`)
- Site contents → Resource policy: checks scripts (evidence: `src/main/browser/site-sessions.ts`)
- Site contents → Ad blocker: creates filter (evidence: `src/main/browser/site-sessions.ts`)
- Site contents → Site permissions: uses permissions (evidence: `src/main/browser/site-sessions.ts`)
- Site contents → Idle workers: manages workers (evidence: `src/main/browser/site-sessions.ts`)
- Ad blocker → Filter engine: uses engine (evidence: `src/main/browser/ad-blocker.ts`)
- Ad blocker → Ad scriptlets: uses scriptlets (evidence: `src/main/browser/ad-blocker.ts`)
- Browser UI → Theme provider: renders within (evidence: `src/renderer/dev/main.tsx`)
- Theme provider → Character profile: loads and saves (evidence: `src/renderer/theme/ThemeProvider.tsx`)
- Theme provider → Theme definitions: selects theme (evidence: `src/renderer/theme/ThemeProvider.tsx`)
- Theme provider → Character types: uses profile types (evidence: `src/renderer/theme/ThemeProvider.tsx`)
- Character profile → Character types: stores profile (evidence: `src/renderer/onboarding/profileStore.ts`)
- Browser controller → History service: uses history (evidence: `src/main/browser/controller.ts`)
- Tab manager → Resource policy: uses resource policy (evidence: `src/main/browser/tab-manager.ts`)