# tanish-8/nexvision architecture

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

- Interactive diagram: https://gitdiagram.com/tanish-8/nexvision
- Repository: https://github.com/tanish-8/nexvision

## Overview

NexVision is a privacy-first browser-agent prototype. A user submits a task through the extension; the background runtime perceives the page, sanitizes sensitive information locally, grounds the task to page elements, plans a validated action, and executes it in the browser before continuing its bounded loop. The README documents this end-to-end flow and the DOM fallback; source excerpts show the service-worker dispatch, perception/privacy calls, and planner/action validation. Some implementation details are unsampled, so those links are shown only where documented.

Main entry points: [`extension/src/background/orchestrator.ts`](https://github.com/tanish-8/nexvision/blob/main/extension/src/background/orchestrator.ts) (Perception orchestrator), [`extension/src/background/demoRunner.ts`](https://github.com/tanish-8/nexvision/blob/main/extension/src/background/demoRunner.ts) (Bounded agent loop), [`extension/src/background/service-worker.ts`](https://github.com/tanish-8/nexvision/blob/main/extension/src/background/service-worker.ts) (Service worker), [`extension/src/shared/messaging.ts`](https://github.com/tanish-8/nexvision/blob/main/extension/src/shared/messaging.ts) (Extension messaging)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extension["Browser extension"]
  node_popup["Extension popup<br/>[popup.ts]"]
  node_service_worker["Service worker<br/>[service-worker.ts]"]
  node_messaging["Extension messaging<br/>[messaging.ts]"]
  node_dom_executor["DOM executor<br/>[domExecutor.ts]"]
end

subgraph group_perception["Page perception"]
  node_dom_perception["DOM perception<br/>[domPerception.ts]"]
  node_screenshot["Screenshot capture<br/>[screenshot.ts]"]
  node_orchestrator["Perception orchestrator<br/>[orchestrator.ts]"]
  node_vision_adapter["Vision adapter"]
  node_vision_runtime["Local vision runtime<br/>[llamaInference.ts]"]
  node_representation["Unified page state<br/>[types.ts]"]
end

subgraph group_privacy["Local privacy"]
  node_privacy_detector["Privacy detector<br/>[detector.ts]"]
  node_sanitizer["Page sanitizer<br/>[sanitizer.ts]"]
end

subgraph group_reasoning["Planning and execution"]
  node_grounding["Element grounding<br/>[grounding.ts]"]
  node_local_agent["Local agent<br/>[localAgent.ts]"]
  node_planner["Action planner<br/>[planner.ts]"]
  node_action_contract["Action validation<br/>[actions.ts]"]
  node_demo_runner["Bounded agent loop<br/>[demoRunner.ts]"]
  node_executor["Action executor<br/>[executor.ts]"]
end

node_user(("User task"))
node_page["Browser page"]
node_local_model["Local Qwen server"]

node_user -->|"submits task"| node_popup
node_popup -->|"sends request"| node_service_worker
node_service_worker -->|"dispatches messages"| node_messaging
node_service_worker -->|"starts agent run"| node_demo_runner
node_page -->|"provides DOM"| node_dom_perception
node_dom_perception -->|"builds page state"| node_representation
node_service_worker -->|"captures screenshot"| node_screenshot
node_screenshot -->|"supplies image"| node_orchestrator
node_orchestrator -->|"requests perception"| node_vision_adapter
node_vision_adapter -.->|"uses inference"| node_vision_runtime
node_vision_runtime -->|"sends inference request"| node_local_model
node_orchestrator -->|"unifies page state"| node_representation
node_orchestrator -->|"checks findings"| node_privacy_detector
node_privacy_detector -->|"provides findings"| node_sanitizer
node_representation -->|"sanitizes page state"| node_sanitizer
node_sanitizer -->|"provides safe state"| node_grounding
node_grounding -->|"grounds task"| node_planner
node_local_agent -->|"requests plan"| node_planner
node_planner -->|"creates and validates"| node_action_contract
node_demo_runner -->|"decomposes task"| node_local_agent
node_demo_runner -.->|"runs perception"| node_orchestrator
node_demo_runner -->|"executes action"| node_executor
node_executor -->|"uses tab messaging"| node_messaging
node_messaging -.->|"routes browser action"| node_dom_executor
node_dom_executor -->|"changes page"| node_page
node_page -->|"is re-perceived"| node_demo_runner

click node_popup "https://github.com/tanish-8/nexvision/blob/main/extension/src/popup/popup.ts"
click node_service_worker "https://github.com/tanish-8/nexvision/blob/main/extension/src/background/service-worker.ts"
click node_messaging "https://github.com/tanish-8/nexvision/blob/main/extension/src/shared/messaging.ts"
click node_dom_perception "https://github.com/tanish-8/nexvision/blob/main/extension/src/content/domPerception.ts"
click node_screenshot "https://github.com/tanish-8/nexvision/blob/main/extension/src/background/screenshot.ts"
click node_orchestrator "https://github.com/tanish-8/nexvision/blob/main/extension/src/background/orchestrator.ts"
click node_vision_adapter "https://github.com/tanish-8/nexvision/blob/main/extension/src/background/llamaVisionAdapter.ts"
click node_vision_runtime "https://github.com/tanish-8/nexvision/blob/main/vision/src/llamaInference.ts"
click node_representation "https://github.com/tanish-8/nexvision/blob/main/extension/src/shared/types.ts"
click node_privacy_detector "https://github.com/tanish-8/nexvision/blob/main/extension/src/privacy/detector.ts"
click node_sanitizer "https://github.com/tanish-8/nexvision/blob/main/extension/src/privacy/sanitizer.ts"
click node_grounding "https://github.com/tanish-8/nexvision/blob/main/extension/src/shared/grounding.ts"
click node_local_agent "https://github.com/tanish-8/nexvision/blob/main/extension/src/background/localAgent.ts"
click node_planner "https://github.com/tanish-8/nexvision/blob/main/extension/src/shared/planner.ts"
click node_action_contract "https://github.com/tanish-8/nexvision/blob/main/extension/src/shared/actions.ts"
click node_demo_runner "https://github.com/tanish-8/nexvision/blob/main/extension/src/background/demoRunner.ts"
click node_executor "https://github.com/tanish-8/nexvision/blob/main/extension/src/background/executor.ts"
click node_dom_executor "https://github.com/tanish-8/nexvision/blob/main/extension/src/content/domExecutor.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_popup,node_service_worker,node_messaging,node_dom_executor,node_page toneBlue
class node_dom_perception,node_screenshot,node_orchestrator,node_vision_adapter,node_vision_runtime,node_representation toneAmber
class node_privacy_detector,node_sanitizer,node_local_model toneMint
class node_grounding,node_local_agent,node_planner,node_action_contract,node_demo_runner,node_executor,node_user toneRose
```

## Components

### Browser extension

- [Extension popup](https://github.com/tanish-8/nexvision/blob/main/extension/src/popup/popup.ts): `extension/src/popup/popup.ts`
- [Service worker](https://github.com/tanish-8/nexvision/blob/main/extension/src/background/service-worker.ts): `extension/src/background/service-worker.ts`
- [Extension messaging](https://github.com/tanish-8/nexvision/blob/main/extension/src/shared/messaging.ts): `extension/src/shared/messaging.ts`
- [DOM executor](https://github.com/tanish-8/nexvision/blob/main/extension/src/content/domExecutor.ts): `extension/src/content/domExecutor.ts`

### Page perception

- [DOM perception](https://github.com/tanish-8/nexvision/blob/main/extension/src/content/domPerception.ts): `extension/src/content/domPerception.ts`
- [Screenshot capture](https://github.com/tanish-8/nexvision/blob/main/extension/src/background/screenshot.ts): `extension/src/background/screenshot.ts`
- [Perception orchestrator](https://github.com/tanish-8/nexvision/blob/main/extension/src/background/orchestrator.ts): `extension/src/background/orchestrator.ts`
- [Vision adapter](https://github.com/tanish-8/nexvision/blob/main/extension/src/background/llamaVisionAdapter.ts): `extension/src/background/llamaVisionAdapter.ts`
- [Local vision runtime](https://github.com/tanish-8/nexvision/blob/main/vision/src/llamaInference.ts): `vision/src/llamaInference.ts`
- [Unified page state](https://github.com/tanish-8/nexvision/blob/main/extension/src/shared/types.ts): `extension/src/shared/types.ts`

### Local privacy

- [Privacy detector](https://github.com/tanish-8/nexvision/blob/main/extension/src/privacy/detector.ts): `extension/src/privacy/detector.ts`
- [Page sanitizer](https://github.com/tanish-8/nexvision/blob/main/extension/src/privacy/sanitizer.ts): `extension/src/privacy/sanitizer.ts`

### Planning and execution

- [Element grounding](https://github.com/tanish-8/nexvision/blob/main/extension/src/shared/grounding.ts): `extension/src/shared/grounding.ts`
- [Local agent](https://github.com/tanish-8/nexvision/blob/main/extension/src/background/localAgent.ts): `extension/src/background/localAgent.ts`
- [Action planner](https://github.com/tanish-8/nexvision/blob/main/extension/src/shared/planner.ts): `extension/src/shared/planner.ts`
- [Action validation](https://github.com/tanish-8/nexvision/blob/main/extension/src/shared/actions.ts): `extension/src/shared/actions.ts`
- [Bounded agent loop](https://github.com/tanish-8/nexvision/blob/main/extension/src/background/demoRunner.ts): `extension/src/background/demoRunner.ts`
- [Action executor](https://github.com/tanish-8/nexvision/blob/main/extension/src/background/executor.ts): `extension/src/background/executor.ts`

### Other components

- **User task**
- **Browser page**
- **Local Qwen server**

## Connections

- User task → Extension popup: submits task (evidence: `README.md`)
- Extension popup → Service worker: sends request (evidence: `README.md`)
- Service worker → Extension messaging: dispatches messages (evidence: `extension/src/background/service-worker.ts`)
- Service worker → Bounded agent loop: starts agent run (evidence: `extension/src/background/service-worker.ts`)
- Browser page → DOM perception: provides DOM (evidence: `README.md`)
- DOM perception → Unified page state: builds page state (evidence: `README.md`)
- Service worker → Screenshot capture: captures screenshot (evidence: `extension/src/background/service-worker.ts`)
- Screenshot capture → Perception orchestrator: supplies image (evidence: `README.md`)
- Perception orchestrator → Vision adapter: requests perception (evidence: `extension/src/background/orchestrator.ts`)
- Vision adapter → Local vision runtime: uses inference
- Local vision runtime → Local Qwen server: sends inference request (evidence: `vision/src/llamaInference.ts`)
- Perception orchestrator → Unified page state: unifies page state (evidence: `README.md`)
- Perception orchestrator → Privacy detector: checks findings (evidence: `extension/src/background/orchestrator.ts`)
- Privacy detector → Page sanitizer: provides findings (evidence: `extension/src/privacy/sanitizer.ts`)
- Unified page state → Page sanitizer: sanitizes page state (evidence: `README.md`)
- Page sanitizer → Element grounding: provides safe state (evidence: `README.md`)
- Element grounding → Action planner: grounds task (evidence: `README.md`)
- Local agent → Action planner: requests plan (evidence: `extension/src/background/localAgent.ts`)
- Action planner → Action validation: creates and validates (evidence: `extension/src/shared/planner.ts`)
- Bounded agent loop → Local agent: decomposes task (evidence: `extension/src/background/demoRunner.ts`)
- Bounded agent loop → Perception orchestrator: runs perception (evidence: `extension/src/background/demoRunner.ts`)
- Bounded agent loop → Action executor: executes action (evidence: `README.md`)
- Action executor → Extension messaging: uses tab messaging (evidence: `extension/src/background/executor.ts`)
- Extension messaging → DOM executor: routes browser action
- DOM executor → Browser page: changes page (evidence: `README.md`)
- Browser page → Bounded agent loop: is re-perceived (evidence: `README.md`)
