# anirbannandy/db-vision architecture

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

- Interactive diagram: https://gitdiagram.com/anirbannandy/db-vision
- Repository: https://github.com/anirbannandy/db-vision

## Overview

db-vision turns a user’s natural-language request and live page context into a validated browser-action plan, then runs it in the active tab or an optional server-side Playwright browser. The main flow is observe, plan, govern, and execute; sidepanel task controls and page analysis/self-healing are additional capabilities. Backend orchestration and core modules are excerpted; some extension messaging and sandbox implementation details are documented in the README rather than shown in source excerpts.

Main entry points: [`backend/app.py`](https://github.com/anirbannandy/db-vision/blob/main/backend/app.py) (FastAPI orchestration), [`extension/sidepanel.js`](https://github.com/anirbannandy/db-vision/blob/main/extension/sidepanel.js) (Sidepanel controls), [`backend/llm_engine.py`](https://github.com/anirbannandy/db-vision/blob/main/backend/llm_engine.py) (LLM engine), [`backend/prompt_builder.py`](https://github.com/anirbannandy/db-vision/blob/main/backend/prompt_builder.py) (Prompt construction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extension["Chrome extension"]
  node_panel["Sidepanel controls<br/>[sidepanel.js]"]
  node_extract["DOM observation<br/>[content.js]"]
  node_actions["Active-tab actions<br/>[content.js]"]
end

subgraph group_backend["Planning backend"]
  node_api["FastAPI orchestration<br/>[app.py]"]
  node_prompts["Prompt construction<br/>[prompt_builder.py]"]
  node_schema["Action validation<br/>[action_schema.py]"]
  node_llm["LLM engine<br/>[llm_engine.py]"]
  node_sessions["Session and task state<br/>[session_manager.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
end

subgraph group_runtime["Execution targets"]
  node_active["Active browser tab"]
  node_sandbox["Playwright sandbox"]
  node_chromium["Sandbox browser"]
end

subgraph group_integrations["Model providers"]
  node_ollama["Ollama"]
  node_gemini["Gemini API"]
end

node_user(("User"))

node_user -->|"enters request"| node_panel
node_panel -->|"requests page context"| node_extract
node_extract -->|"returns DOM context"| node_panel
node_panel -->|"submits task"| node_api
node_api -->|"builds prompts"| node_prompts
node_prompts -->|"uses action reference"| node_schema
node_api -->|"requests plan"| node_llm
node_api -->|"validates actions"| node_schema
node_api -->|"tracks task state"| node_sessions
node_llm -->|"queries locally"| node_ollama
node_llm -->|"queries optionally"| node_gemini
node_config -->|"configures providers"| node_llm
node_api -->|"loads settings"| node_config
node_api -->|"returns action plan"| node_panel
node_panel -->|"dispatches actions"| node_actions
node_actions -->|"applies DOM events"| node_active
node_api -.->|"offers alternate execution"| node_sandbox
node_sandbox -.->|"drives browser"| node_chromium
node_panel -->|"requests self-healing"| node_api
node_api -->|"builds repair prompt"| node_prompts
node_panel -.->|"requests page analysis"| node_api

click node_panel "https://github.com/anirbannandy/db-vision/blob/main/extension/sidepanel.js"
click node_extract "https://github.com/anirbannandy/db-vision/blob/main/extension/content.js"
click node_actions "https://github.com/anirbannandy/db-vision/blob/main/extension/content.js"
click node_api "https://github.com/anirbannandy/db-vision/blob/main/backend/app.py"
click node_prompts "https://github.com/anirbannandy/db-vision/blob/main/backend/prompt_builder.py"
click node_schema "https://github.com/anirbannandy/db-vision/blob/main/backend/action_schema.py"
click node_llm "https://github.com/anirbannandy/db-vision/blob/main/backend/llm_engine.py"
click node_sessions "https://github.com/anirbannandy/db-vision/blob/main/backend/session_manager.py"
click node_config "https://github.com/anirbannandy/db-vision/blob/main/backend/config.py"
click node_sandbox "https://github.com/anirbannandy/db-vision/tree/main/backend"

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_panel,node_extract,node_actions,node_user toneBlue
class node_api,node_prompts,node_schema,node_llm,node_sessions,node_config toneAmber
class node_active,node_sandbox,node_chromium toneMint
class node_ollama,node_gemini toneRose
```

## Components

### Chrome extension

- [Sidepanel controls](https://github.com/anirbannandy/db-vision/blob/main/extension/sidepanel.js): `extension/sidepanel.js`
- [DOM observation](https://github.com/anirbannandy/db-vision/blob/main/extension/content.js): `extension/content.js`
- [Active-tab actions](https://github.com/anirbannandy/db-vision/blob/main/extension/content.js): `extension/content.js`

### Planning backend

- [FastAPI orchestration](https://github.com/anirbannandy/db-vision/blob/main/backend/app.py): `backend/app.py`
- [Prompt construction](https://github.com/anirbannandy/db-vision/blob/main/backend/prompt_builder.py): `backend/prompt_builder.py`
- [Action validation](https://github.com/anirbannandy/db-vision/blob/main/backend/action_schema.py): `backend/action_schema.py`
- [LLM engine](https://github.com/anirbannandy/db-vision/blob/main/backend/llm_engine.py): `backend/llm_engine.py`
- [Session and task state](https://github.com/anirbannandy/db-vision/blob/main/backend/session_manager.py): `backend/session_manager.py`
- [Runtime configuration](https://github.com/anirbannandy/db-vision/blob/main/backend/config.py): `backend/config.py`

### Execution targets

- **Active browser tab**
- [Playwright sandbox](https://github.com/anirbannandy/db-vision/tree/main/backend): `backend`
- **Sandbox browser**

### Model providers

- **Ollama**
- **Gemini API**

### Other components

- **User**

## Connections

- User → Sidepanel controls: enters request (evidence: `README.md`)
- Sidepanel controls → DOM observation: requests page context (evidence: `README.md`)
- DOM observation → Sidepanel controls: returns DOM context (evidence: `README.md`)
- Sidepanel controls → FastAPI orchestration: submits task (evidence: `extension/sidepanel.js`)
- FastAPI orchestration → Prompt construction: builds prompts (evidence: `backend/app.py`)
- Prompt construction → Action validation: uses action reference (evidence: `backend/prompt_builder.py`)
- FastAPI orchestration → LLM engine: requests plan (evidence: `backend/app.py`)
- FastAPI orchestration → Action validation: validates actions (evidence: `backend/app.py`)
- FastAPI orchestration → Session and task state: tracks task state (evidence: `backend/app.py`)
- LLM engine → Ollama: queries locally (evidence: `backend/llm_engine.py`)
- LLM engine → Gemini API: queries optionally (evidence: `backend/llm_engine.py`)
- Runtime configuration → LLM engine: configures providers (evidence: `backend/llm_engine.py`)
- FastAPI orchestration → Runtime configuration: loads settings (evidence: `backend/app.py`)
- FastAPI orchestration → Sidepanel controls: returns action plan (evidence: `README.md`)
- Sidepanel controls → Active-tab actions: dispatches actions (evidence: `README.md`)
- Active-tab actions → Active browser tab: applies DOM events (evidence: `extension/content.js`)
- FastAPI orchestration → Playwright sandbox: offers alternate execution (evidence: `README.md`)
- Playwright sandbox → Sandbox browser: drives browser (evidence: `README.md`)
- Sidepanel controls → FastAPI orchestration: requests self-healing (evidence: `extension/sidepanel.js`)
- FastAPI orchestration → Prompt construction: builds repair prompt (evidence: `backend/app.py`)
- Sidepanel controls → FastAPI orchestration: requests page analysis
