# siva010505/xenon architecture

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

- Interactive diagram: https://gitdiagram.com/siva010505/xenon
- Repository: https://github.com/siva010505/xenon

## Overview

#### Purpose and operating model
XENON is a Windows-focused AI browser assistant for a user-launched Chrome instance. A Chrome side-panel extension collects tasks and settings, then reaches Python automation services that control or inspect the host browser through its debugging-enabled session. Setup scripts provision dependencies, native messaging registration, and the dedicated Chrome launch profile.

Key entry points: `setup.bat`, `Launch_Xenon_Chrome.bat`, `server.py`, and `extension/manifest.json`.

#### Chrome extension UI and lifecycle
The extension is the user-facing boundary. Its side panel hosts task interaction and settings/personal-information capture; speech support is a separate extension page. A background/service-worker layer manages extension lifecycle and communication outside the side-panel document.

Core paths:
- `extension/sidepanel.html`
- `extension/sidepanel.js`
- `extension/service-worker.js`
- `extension/speech.js`

#### Native messaging bridge
Chrome native messaging provides a local process boundary between the extension and Python. The extension declares a native host, while the bridge reads/writes the native-messaging protocol and can mediate requests to local automation/server processes. Windows installation scripts register the host manifest with Chrome.

Core paths:
- `extension/com.xenon.server.json`
- `extension/host/manifest.json`
- `extension/host/bridge.py`
- `native_host.py`

#### Python server and agent orchestration
The Python backend is the control plane for requests originating from the extension/native host. It selects and runs AI-driven browser automation workflows, including general browser-use tasks and deeper research workflows. Agent code is separated from browser primitives so task strategy can evolve independently of Chrome connection details.

Core paths:
- `server.py`
- `src/agent/browser_use/browser_use_agent.py`
- `src/agent/deep_research/deep_research_agent.py`
- `src/controller/custom_controller.py`

#### Browser automation boundary
Browser integration is encapsulated in custom browser and context modules. This is the boundary where agent decisions become browser actions—navigation, DOM/vision-based interaction, extraction, and form completion—against the debugging-enabled Chrome session rather than an extension-owned page model.

Core paths:
- `src/browser/custom_browser.py`
- `src/browser/custom_context.py`
- `Launch_Xenon_Chrome.bat`

#### LLM, configuration, and tool integration
Agent execution is provider-agnostic: LLM provider selection and runtime configuration are centralized in utilities, supporting cloud and local model providers named in the project documentation. An MCP client indicates an additional external-tool/protocol integration boundary available to agents.

Core paths:
- `src/utils/llm_provider.py`
- `src/utils/config.py`
- `src/utils/mcp_client.py`
- `requirements.txt`

#### Runtime and deployment assumptions
The material runtime is Python 3.11+ on Windows, Chrome with a dedicated debugging profile, and extension APIs/native messaging. Setup installs Python and browser-automation dependencies, configures a hidden/background launcher, and registers native-host integration. External services are the user-selected LLM APIs or local Ollama endpoint; credentials are supplied through the extension settings flow.

Core paths:
- `setup.bat`
- `setup_helper.py`
- `register_native_host.bat`
- `start_xenon_silent.vbs`

Main entry points: [`server.py`](https://github.com/siva010505/xenon/blob/main/server.py) (Automation Server), [`src/controller/custom_controller.py`](https://github.com/siva010505/xenon/blob/main/src/controller/custom_controller.py) (Custom Controller), [`extension/service-worker.js`](https://github.com/siva010505/xenon/blob/main/extension/service-worker.js) (Service Worker), [`extension/host/manifest.json`](https://github.com/siva010505/xenon/blob/main/extension/host/manifest.json) (Native Host Manifest)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bootstrap["Windows Setup"]
  node_setup["Setup<br/>installer<br/>[setup.bat]"]
  node_setup_helper["Setup Helper<br/>provisioning<br/>[setup_helper.py]"]
  node_native_registration["Native Host Registration<br/>registration script"]
end

subgraph group_extension["Chrome Extension"]
  node_side_panel["Side Panel UI<br/>extension UI<br/>[sidepanel.js]"]
  node_extension_manifest["Extension Manifest<br/>[manifest.json]"]
  node_service_worker["Service Worker<br/>extension lifecycle<br/>[service-worker.js]"]
  node_speech_ui["Speech Support<br/>extension page<br/>[speech.js]"]
end

subgraph group_bridge["Native Messaging"]
  node_native_host_manifest["Native Host Manifest<br/>[manifest.json]"]
  node_native_bridge["Native Bridge<br/>native messaging protocol<br/>[bridge.py]"]
  node_native_host["Native Host Entrypoint<br/>host process<br/>[native_host.py]"]
end

subgraph group_backend["Python Control Plane"]
  node_server["Automation Server<br/>Python server<br/>[server.py]"]
  node_browser_use_agent["Browser-Use Agent<br/>task agent"]
  node_research_agent["Deep Research Agent"]
  node_controller["Custom Controller<br/>agent controller"]
end

subgraph group_browser["Browser Automation"]
  node_chrome_launcher["Debug Chrome Launcher<br/>browser launcher"]
  node_browser_adapter["Custom Browser<br/>Chrome adapter<br/>[custom_browser.py]"]
  node_browser_context["Custom Context<br/>browser context<br/>[custom_context.py]"]
end

subgraph group_integrations["Model &amp; Tool Integrations"]
  node_runtime_config["Runtime Configuration<br/>[config.py]"]
  node_llm_provider["LLM Provider<br/>provider abstraction<br/>[llm_provider.py]"]
  node_mcp_client["MCP Client<br/>tool protocol client<br/>[mcp_client.py]"]
  node_external_llms{{"LLM APIs / Ollama<br/>external model service"}}
end

node_setup -->|"runs"| node_setup_helper
node_setup -->|"installs"| node_native_registration
node_native_registration -->|"registers"| node_native_host_manifest
node_extension_manifest -->|"declares host"| node_native_host_manifest
node_side_panel -->|"extension messages"| node_service_worker
node_speech_ui -->|"extension messages"| node_service_worker
node_service_worker -->|"native messaging"| node_native_bridge
node_native_host_manifest -->|"launches"| node_native_host
node_native_host -->|"hosts"| node_native_bridge
node_native_bridge -->|"local requests"| node_server
node_server -->|"dispatches tasks"| node_browser_use_agent
node_server -->|"dispatches research"| node_research_agent
node_browser_use_agent -->|"uses"| node_controller
node_research_agent -->|"uses"| node_controller
node_controller -->|"browser actions"| node_browser_adapter
node_browser_adapter -->|"creates context"| node_browser_context
node_chrome_launcher -->|"debugging session"| node_browser_adapter
node_server -->|"loads"| node_runtime_config
node_runtime_config -->|"configures"| node_llm_provider
node_llm_provider -->|"invokes"| node_external_llms
node_controller -.->|"uses tools"| node_mcp_client

click node_setup "https://github.com/siva010505/xenon/blob/main/setup.bat"
click node_setup_helper "https://github.com/siva010505/xenon/blob/main/setup_helper.py"
click node_native_registration "https://github.com/siva010505/xenon/blob/main/register_native_host.bat"
click node_chrome_launcher "https://github.com/siva010505/xenon/blob/main/Launch_Xenon_Chrome.bat"
click node_side_panel "https://github.com/siva010505/xenon/blob/main/extension/sidepanel.js"
click node_extension_manifest "https://github.com/siva010505/xenon/blob/main/extension/manifest.json"
click node_service_worker "https://github.com/siva010505/xenon/blob/main/extension/service-worker.js"
click node_speech_ui "https://github.com/siva010505/xenon/blob/main/extension/speech.js"
click node_native_host_manifest "https://github.com/siva010505/xenon/blob/main/extension/host/manifest.json"
click node_native_bridge "https://github.com/siva010505/xenon/blob/main/extension/host/bridge.py"
click node_native_host "https://github.com/siva010505/xenon/blob/main/native_host.py"
click node_server "https://github.com/siva010505/xenon/blob/main/server.py"
click node_browser_use_agent "https://github.com/siva010505/xenon/blob/main/src/agent/browser_use/browser_use_agent.py"
click node_research_agent "https://github.com/siva010505/xenon/blob/main/src/agent/deep_research/deep_research_agent.py"
click node_controller "https://github.com/siva010505/xenon/blob/main/src/controller/custom_controller.py"
click node_browser_adapter "https://github.com/siva010505/xenon/blob/main/src/browser/custom_browser.py"
click node_browser_context "https://github.com/siva010505/xenon/blob/main/src/browser/custom_context.py"
click node_runtime_config "https://github.com/siva010505/xenon/blob/main/src/utils/config.py"
click node_llm_provider "https://github.com/siva010505/xenon/blob/main/src/utils/llm_provider.py"
click node_mcp_client "https://github.com/siva010505/xenon/blob/main/src/utils/mcp_client.py"

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_setup,node_setup_helper,node_native_registration toneBlue
class node_side_panel,node_extension_manifest,node_service_worker,node_speech_ui toneAmber
class node_native_host_manifest,node_native_bridge,node_native_host toneMint
class node_server,node_browser_use_agent,node_research_agent,node_controller toneRose
class node_chrome_launcher,node_browser_adapter,node_browser_context toneIndigo
class node_runtime_config,node_llm_provider,node_mcp_client,node_external_llms toneTeal
```

## Components

### Windows Setup

- [Setup](https://github.com/siva010505/xenon/blob/main/setup.bat): installer · Provisions dependencies and local integration. · `setup.bat`
- [Setup Helper](https://github.com/siva010505/xenon/blob/main/setup_helper.py): provisioning · `setup_helper.py`
- [Native Host Registration](https://github.com/siva010505/xenon/blob/main/register_native_host.bat): registration script · Registers the Chrome native-messaging host on Windows. · `register_native_host.bat`

### Chrome Extension

- [Side Panel UI](https://github.com/siva010505/xenon/blob/main/extension/sidepanel.js): extension UI · Collects tasks, settings, and personal information. · `extension/sidepanel.js`
- [Extension Manifest](https://github.com/siva010505/xenon/blob/main/extension/manifest.json): extension manifest · Declares extension capabilities and native-host access. · `extension/manifest.json`
- [Service Worker](https://github.com/siva010505/xenon/blob/main/extension/service-worker.js): extension lifecycle · Manages background lifecycle and communication. · `extension/service-worker.js`
- [Speech Support](https://github.com/siva010505/xenon/blob/main/extension/speech.js): extension page · `extension/speech.js`

### Native Messaging

- [Native Host Manifest](https://github.com/siva010505/xenon/blob/main/extension/host/manifest.json): native host manifest · Defines the host executable and allowed Chrome extension. · `extension/host/manifest.json`
- [Native Bridge](https://github.com/siva010505/xenon/blob/main/extension/host/bridge.py): native messaging protocol · Translates Chrome native-messaging streams into local requests. · `extension/host/bridge.py`
- [Native Host Entrypoint](https://github.com/siva010505/xenon/blob/main/native_host.py): host process · `native_host.py`

### Python Control Plane

- [Automation Server](https://github.com/siva010505/xenon/blob/main/server.py): Python server · Control plane for extension-originated automation requests. · `server.py`
- [Browser-Use Agent](https://github.com/siva010505/xenon/blob/main/src/agent/browser_use/browser_use_agent.py): task agent · Runs general AI-driven browser tasks. · `src/agent/browser_use/browser_use_agent.py`
- [Deep Research Agent](https://github.com/siva010505/xenon/blob/main/src/agent/deep_research/deep_research_agent.py): research agent · Runs deeper research workflows. · `src/agent/deep_research/deep_research_agent.py`
- [Custom Controller](https://github.com/siva010505/xenon/blob/main/src/controller/custom_controller.py): agent controller · Coordinates agent actions and task execution. · `src/controller/custom_controller.py`

### Browser Automation

- [Debug Chrome Launcher](https://github.com/siva010505/xenon/blob/main/Launch_Xenon_Chrome.bat): browser launcher · Launches Chrome with XENON's dedicated debugging profile. · `Launch_Xenon_Chrome.bat`
- [Custom Browser](https://github.com/siva010505/xenon/blob/main/src/browser/custom_browser.py): Chrome adapter · Connects agent actions to the debugging-enabled Chrome session. · `src/browser/custom_browser.py`
- [Custom Context](https://github.com/siva010505/xenon/blob/main/src/browser/custom_context.py): browser context · Provides navigation, interaction, extraction, and form-completion context. · `src/browser/custom_context.py`

### Model & Tool Integrations

- [Runtime Configuration](https://github.com/siva010505/xenon/blob/main/src/utils/config.py): configuration · Centralizes provider selection and runtime settings. · `src/utils/config.py`
- [LLM Provider](https://github.com/siva010505/xenon/blob/main/src/utils/llm_provider.py): provider abstraction · Selects cloud or local model providers. · `src/utils/llm_provider.py`
- [MCP Client](https://github.com/siva010505/xenon/blob/main/src/utils/mcp_client.py): tool protocol client · Connects agents to external MCP tools. · `src/utils/mcp_client.py`
- **LLM APIs / Ollama**: external model service · User-selected cloud APIs or local Ollama endpoint.

## Connections

- Setup → Setup Helper: runs
- Setup → Native Host Registration: installs
- Native Host Registration → Native Host Manifest: registers
- Extension Manifest → Native Host Manifest: declares host
- Side Panel UI → Service Worker: extension messages
- Speech Support → Service Worker: extension messages
- Service Worker → Native Bridge: native messaging
- Native Host Manifest → Native Host Entrypoint: launches
- Native Host Entrypoint → Native Bridge: hosts
- Native Bridge → Automation Server: local requests
- Automation Server → Browser-Use Agent: dispatches tasks
- Automation Server → Deep Research Agent: dispatches research
- Browser-Use Agent → Custom Controller: uses
- Deep Research Agent → Custom Controller: uses
- Custom Controller → Custom Browser: browser actions
- Custom Browser → Custom Context: creates context
- Debug Chrome Launcher → Custom Browser: debugging session
- Automation Server → Runtime Configuration: loads
- Runtime Configuration → LLM Provider: configures
- LLM Provider → LLM APIs / Ollama: invokes
- Custom Controller → MCP Client: uses tools