# gowtham2036/browser-ai architecture

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

- Interactive diagram: https://gitdiagram.com/gowtham2036/browser-ai
- Repository: https://github.com/gowtham2036/browser-ai

## Overview

#### Purpose and Runtime

Browser-AI is a cross-platform desktop browser experience with AI-assisted browsing. It combines a React/Vite renderer with a Rust/Tauri desktop host. The application entry points are `src/main.tsx` for the renderer and `src-tauri/src/main.rs` / `src-tauri/src/lib.rs` for the native process.

#### Desktop Host and Security Boundary

Tauri packages and launches the frontend as a desktop application, owns native-window integration, and applies capability/permission policy. Core host configuration and access boundaries are in:
- `src-tauri/tauri.conf.json`
- `src-tauri/capabilities/default.json`
- `src-tauri/permissions/app.toml`

Rust dependencies and build behavior are defined by `src-tauri/Cargo.toml` and `src-tauri/build.rs`.

#### Application Composition

`src/App.tsx` is the renderer-level composition root, with global styling in `src/App.css` and `src/index.css`. It assembles the browser surface, navigation controls, tab UI, reader mode, settings, and side-panel workflows:
- `src/components/BrowserShell.tsx`
- `src/components/TabBar.tsx`
- `src/components/Omnibox.tsx`

#### Browser State and UI Control Flow

The browser’s shared client-side state is centered in `src/store/browserStore.ts`. Browser UI components read and mutate this store to drive navigation, tab selection, panels, reader-mode state, and related application state. Common domain contracts are concentrated in `src/types/index.ts`, separating UI and agent services from concrete state representations.

#### AI Agent Pipeline

The AI subsystem is organized as an explicit observe-plan/loop-execute flow. `src/services/agent.ts` is the service-facing agent entry point; the implementation is divided into:
- `src/services/agent/agentLoop.ts` — coordinates iterative agent work.
- `src/services/agent/observer.ts` — derives browser/page context for the agent.
- `src/services/agent/actions.ts` and `src/services/agent/executor.ts` — define and perform browser actions.

This is the main control boundary between model-directed intent and mutations to browser/UI state.

#### AI and Persistence Services

`src/services/ai.ts` encapsulates AI/model-facing integration, keeping model interaction outside React components and the agent executor. `src/services/db.ts` provides persistence access behind a frontend service boundary. Shared service-level behavior lives in `src/services/utils.ts`. External AI and storage providers are not identified in the supplied repository metadata; their concrete configuration should be verified in these service files.

#### Agent Visibility and User Interaction

The side panel exposes the agent as a user-facing workflow rather than an opaque background process. Its chat, controls, status/timeline, debugging, and intelligence views are split across:
- `src/components/sidepanel/SidePanelChat.tsx`
- `src/components/sidepanel/AgentControls.tsx`
- `src/components/sidepanel/AgentTimeline.tsx`

`src/components/sidepanel/AgentDebug.tsx` and `src/components/sidepanel/IntelPanel.tsx` provide observability/context views, while `src/components/SidePanel.tsx` integrates them with the main browser shell.

Main entry points: [`src/store/browserStore.ts`](https://github.com/gowtham2036/browser-ai/blob/master/src/store/browserStore.ts) (Browser Store), [`src/App.tsx`](https://github.com/gowtham2036/browser-ai/blob/master/src/App.tsx) (App Composition), [`src/components/SidePanel.tsx`](https://github.com/gowtham2036/browser-ai/blob/master/src/components/SidePanel.tsx) (Side Panel), [`src-tauri/src/main.rs`](https://github.com/gowtham2036/browser-ai/blob/master/src-tauri/src/main.rs) (Tauri Runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_renderer["React Renderer"]
  node_renderer_entry(("Renderer Entry<br/>React/Vite entry<br/>[main.tsx]"))
  node_app["App Composition<br/>React root<br/>[App.tsx]"]
  node_browser_shell["Browser Shell<br/>browser UI<br/>[BrowserShell.tsx]"]
  node_navigation_ui["Tabs &amp; Omnibox<br/>navigation UI<br/>[TabBar.tsx]"]
  node_omnibox["Omnibox<br/>navigation UI<br/>[Omnibox.tsx]"]
  node_side_panel["Side Panel<br/>agent workflow UI<br/>[SidePanel.tsx]"]
  node_agent_chat["Agent Chat<br/>side-panel view<br/>[SidePanelChat.tsx]"]
  node_agent_controls["Agent Controls<br/>side-panel view<br/>[AgentControls.tsx]"]
  node_agent_timeline["Agent Timeline<br/>side-panel view<br/>[AgentTimeline.tsx]"]
  node_browser_store[("Browser Store<br/>shared client state<br/>[browserStore.ts]")]
  node_contracts["Domain Contracts<br/>TypeScript types<br/>[index.ts]"]
end

subgraph group_agent["AI Agent Pipeline"]
  node_agent_entry["Agent Service<br/>agent API<br/>[agent.ts]"]
  node_agent_loop["Agent Loop<br/>orchestrator<br/>[agentLoop.ts]"]
  node_observer["Page Observer<br/>context derivation<br/>[observer.ts]"]
  node_ai_service["AI Service<br/>model integration<br/>[ai.ts]"]
  node_actions["Agent Actions<br/>action contracts<br/>[actions.ts]"]
  node_executor["Action Executor<br/>browser mutation<br/>[executor.ts]"]
  node_db_service[("Persistence Service<br/>storage boundary<br/>[db.ts]")]
end

subgraph group_host["Tauri Host"]
  node_tauri_runtime{{"Tauri Runtime<br/>native desktop host<br/>[main.rs]"}}
  node_tauri_library["Host Library<br/>Rust host logic<br/>[lib.rs]"]
  node_security_policy["Capabilities &amp; Permissions<br/>security policy<br/>[default.json]"]
  node_tauri_config["Tauri Configuration<br/>host configuration<br/>[tauri.conf.json]"]
end

node_renderer_entry -->|"mounts"| node_app
node_app -->|"composes"| node_browser_shell
node_app -->|"composes"| node_navigation_ui
node_app -->|"composes"| node_omnibox
node_app -->|"composes"| node_side_panel
node_browser_shell -->|"reads and mutates"| node_browser_store
node_navigation_ui -->|"reads and mutates"| node_browser_store
node_omnibox -->|"navigates via"| node_browser_store
node_side_panel -->|"hosts"| node_agent_chat
node_side_panel -->|"hosts"| node_agent_controls
node_side_panel -->|"hosts"| node_agent_timeline
node_side_panel -->|"starts workflows"| node_agent_entry
node_agent_entry -->|"delegates to"| node_agent_loop
node_agent_loop -->|"observes"| node_observer
node_observer -->|"reads context"| node_browser_store
node_agent_loop -->|"requests plan"| node_ai_service
node_agent_loop -->|"selects"| node_actions
node_actions -->|"defines"| node_executor
node_executor -->|"mutates"| node_browser_store
node_agent_entry -->|"persists data"| node_db_service
node_browser_store -.->|"uses"| node_contracts
node_tauri_runtime -->|"launches"| node_renderer_entry
node_tauri_runtime -->|"initializes"| node_tauri_library
node_tauri_runtime -->|"enforces"| node_security_policy
node_tauri_runtime -->|"uses"| node_tauri_config

click node_renderer_entry "https://github.com/gowtham2036/browser-ai/blob/master/src/main.tsx"
click node_app "https://github.com/gowtham2036/browser-ai/blob/master/src/App.tsx"
click node_browser_shell "https://github.com/gowtham2036/browser-ai/blob/master/src/components/BrowserShell.tsx"
click node_navigation_ui "https://github.com/gowtham2036/browser-ai/blob/master/src/components/TabBar.tsx"
click node_omnibox "https://github.com/gowtham2036/browser-ai/blob/master/src/components/Omnibox.tsx"
click node_side_panel "https://github.com/gowtham2036/browser-ai/blob/master/src/components/SidePanel.tsx"
click node_agent_chat "https://github.com/gowtham2036/browser-ai/blob/master/src/components/sidepanel/SidePanelChat.tsx"
click node_agent_controls "https://github.com/gowtham2036/browser-ai/blob/master/src/components/sidepanel/AgentControls.tsx"
click node_agent_timeline "https://github.com/gowtham2036/browser-ai/blob/master/src/components/sidepanel/AgentTimeline.tsx"
click node_browser_store "https://github.com/gowtham2036/browser-ai/blob/master/src/store/browserStore.ts"
click node_contracts "https://github.com/gowtham2036/browser-ai/blob/master/src/types/index.ts"
click node_agent_entry "https://github.com/gowtham2036/browser-ai/blob/master/src/services/agent.ts"
click node_agent_loop "https://github.com/gowtham2036/browser-ai/blob/master/src/services/agent/agentLoop.ts"
click node_observer "https://github.com/gowtham2036/browser-ai/blob/master/src/services/agent/observer.ts"
click node_ai_service "https://github.com/gowtham2036/browser-ai/blob/master/src/services/ai.ts"
click node_actions "https://github.com/gowtham2036/browser-ai/blob/master/src/services/agent/actions.ts"
click node_executor "https://github.com/gowtham2036/browser-ai/blob/master/src/services/agent/executor.ts"
click node_db_service "https://github.com/gowtham2036/browser-ai/blob/master/src/services/db.ts"
click node_tauri_runtime "https://github.com/gowtham2036/browser-ai/blob/master/src-tauri/src/main.rs"
click node_tauri_library "https://github.com/gowtham2036/browser-ai/blob/master/src-tauri/src/lib.rs"
click node_security_policy "https://github.com/gowtham2036/browser-ai/blob/master/src-tauri/capabilities/default.json"
click node_tauri_config "https://github.com/gowtham2036/browser-ai/blob/master/src-tauri/tauri.conf.json"

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_renderer_entry,node_app,node_browser_shell,node_navigation_ui,node_omnibox,node_side_panel,node_agent_chat,node_agent_controls,node_agent_timeline,node_browser_store,node_contracts toneBlue
class node_agent_entry,node_agent_loop,node_observer,node_ai_service,node_actions,node_executor,node_db_service toneAmber
class node_tauri_runtime,node_tauri_library,node_security_policy,node_tauri_config toneMint
```

## Components

### React Renderer

Browser UI and client-side workflows.

- [Renderer Entry](https://github.com/gowtham2036/browser-ai/blob/master/src/main.tsx): React/Vite entry · `src/main.tsx`
- [App Composition](https://github.com/gowtham2036/browser-ai/blob/master/src/App.tsx): React root · Assembles the browser experience and primary workflows. · `src/App.tsx`
- [Browser Shell](https://github.com/gowtham2036/browser-ai/blob/master/src/components/BrowserShell.tsx): browser UI · `src/components/BrowserShell.tsx`
- [Tabs & Omnibox](https://github.com/gowtham2036/browser-ai/blob/master/src/components/TabBar.tsx): navigation UI · `src/components/TabBar.tsx`
- [Omnibox](https://github.com/gowtham2036/browser-ai/blob/master/src/components/Omnibox.tsx): navigation UI · `src/components/Omnibox.tsx`
- [Side Panel](https://github.com/gowtham2036/browser-ai/blob/master/src/components/SidePanel.tsx): agent workflow UI · Integrates chat, controls, status, debug, and intelligence views. · `src/components/SidePanel.tsx`
- [Agent Chat](https://github.com/gowtham2036/browser-ai/blob/master/src/components/sidepanel/SidePanelChat.tsx): side-panel view · `src/components/sidepanel/SidePanelChat.tsx`
- [Agent Controls](https://github.com/gowtham2036/browser-ai/blob/master/src/components/sidepanel/AgentControls.tsx): side-panel view · `src/components/sidepanel/AgentControls.tsx`
- [Agent Timeline](https://github.com/gowtham2036/browser-ai/blob/master/src/components/sidepanel/AgentTimeline.tsx): side-panel view · `src/components/sidepanel/AgentTimeline.tsx`
- [Browser Store](https://github.com/gowtham2036/browser-ai/blob/master/src/store/browserStore.ts): shared client state · Owns navigation, tabs, panels, reader mode, and related browser state. · `src/store/browserStore.ts`
- [Domain Contracts](https://github.com/gowtham2036/browser-ai/blob/master/src/types/index.ts): TypeScript types · `src/types/index.ts`

### AI Agent Pipeline

Observe, plan, and execute browser actions.

- [Agent Service](https://github.com/gowtham2036/browser-ai/blob/master/src/services/agent.ts): agent API · Service-facing entry point for AI workflows. · `src/services/agent.ts`
- [Agent Loop](https://github.com/gowtham2036/browser-ai/blob/master/src/services/agent/agentLoop.ts): orchestrator · Coordinates iterative agent work. · `src/services/agent/agentLoop.ts`
- [Page Observer](https://github.com/gowtham2036/browser-ai/blob/master/src/services/agent/observer.ts): context derivation · Derives browser and page context. · `src/services/agent/observer.ts`
- [AI Service](https://github.com/gowtham2036/browser-ai/blob/master/src/services/ai.ts): model integration · Keeps model interaction outside React and execution code. · `src/services/ai.ts`
- [Agent Actions](https://github.com/gowtham2036/browser-ai/blob/master/src/services/agent/actions.ts): action contracts · `src/services/agent/actions.ts`
- [Action Executor](https://github.com/gowtham2036/browser-ai/blob/master/src/services/agent/executor.ts): browser mutation · Performs model-directed browser actions. · `src/services/agent/executor.ts`
- [Persistence Service](https://github.com/gowtham2036/browser-ai/blob/master/src/services/db.ts): storage boundary · Frontend persistence access boundary. · `src/services/db.ts`

### Tauri Host

Native desktop runtime and security boundary.

- [Tauri Runtime](https://github.com/gowtham2036/browser-ai/blob/master/src-tauri/src/main.rs): native desktop host · Packages and launches the renderer with native-window integration. · `src-tauri/src/main.rs`
- [Host Library](https://github.com/gowtham2036/browser-ai/blob/master/src-tauri/src/lib.rs): Rust host logic · `src-tauri/src/lib.rs`
- [Capabilities & Permissions](https://github.com/gowtham2036/browser-ai/blob/master/src-tauri/capabilities/default.json): security policy · Defines allowed desktop access. · `src-tauri/capabilities/default.json`
- [Tauri Configuration](https://github.com/gowtham2036/browser-ai/blob/master/src-tauri/tauri.conf.json): host configuration · `src-tauri/tauri.conf.json`

## Connections

- Renderer Entry → App Composition: mounts
- App Composition → Browser Shell: composes
- App Composition → Tabs & Omnibox: composes
- App Composition → Omnibox: composes
- App Composition → Side Panel: composes
- Browser Shell → Browser Store: reads and mutates
- Tabs & Omnibox → Browser Store: reads and mutates
- Omnibox → Browser Store: navigates via
- Side Panel → Agent Chat: hosts
- Side Panel → Agent Controls: hosts
- Side Panel → Agent Timeline: hosts
- Side Panel → Agent Service: starts workflows
- Agent Service → Agent Loop: delegates to
- Agent Loop → Page Observer: observes
- Page Observer → Browser Store: reads context
- Agent Loop → AI Service: requests plan
- Agent Loop → Agent Actions: selects
- Agent Actions → Action Executor: defines
- Action Executor → Browser Store: mutates
- Agent Service → Persistence Service: persists data
- Browser Store → Domain Contracts: uses
- Tauri Runtime → Renderer Entry: launches
- Tauri Runtime → Host Library: initializes
- Tauri Runtime → Capabilities & Permissions: enforces
- Tauri Runtime → Tauri Configuration: uses