# moritzkremb/jev-voice-browser architecture

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

- Interactive diagram: https://gitdiagram.com/moritzkremb/jev-voice-browser
- Repository: https://github.com/moritzkremb/jev-voice-browser

## Overview

voice-browser is a Node application for controlling a real Chromium browser through spoken or typed commands. Its main workflow streams transcript updates from the control page to a server-side controller, which sends page and conversation context to Jev, applies code-owned decision gates, then executes browser actions and refreshes the page snapshot. Major capabilities include navigation, web and site-specific search, element selection, typing, scrolling, tabs, history, corrections, and destructive-action confirmation. The graph reflects the documented workflow; some details rely on the README because source excerpts are partial.

Main entry points: [`src/controller.js`](https://github.com/moritzkremb/jev-voice-browser/blob/main/src/controller.js) (Command controller), [`src/jev.js`](https://github.com/moritzkremb/jev-voice-browser/blob/main/src/jev.js) (Jev request builder), [`src/browser.js`](https://github.com/moritzkremb/jev-voice-browser/blob/main/src/browser.js) (Browser manager), [`src/public/index.html`](https://github.com/moritzkremb/jev-voice-browser/blob/main/src/public/index.html) (Control page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_control_page["Control page<br/>[index.html]"]
  node_server["HTTP and WS server<br/>[server.js]"]
end

subgraph group_decision["Interpretation and policy"]
  node_controller["Command controller<br/>[controller.js]"]
  node_jev["Jev request builder<br/>[jev.js]"]
  node_policy["Decision policy<br/>[policy.js]"]
  node_spans["Candidate spans<br/>[spans.js]"]
  node_constants["Questions and thresholds<br/>[constants.js]"]
end

subgraph group_browser["Browser interaction"]
  node_browser_manager["Browser manager<br/>[browser.js]"]
  node_snapshot["Page snapshot<br/>[snapshot.js]"]
  node_executor["Action executor<br/>[executor.js]"]
  node_overlay["Page feedback overlay<br/>[overlay.js]"]
end

subgraph group_services["External services"]
  node_speech["Web Speech API"]
  node_jev_service["TypeSafe Jev"]
  node_chromium["Playwright Chromium"]
end

node_user(("User"))
node_microphone(("Microphone"))

node_user -->|"speaks into"| node_microphone
node_microphone -->|"captures audio"| node_speech
node_speech -->|"transcribes speech"| node_control_page
node_user -->|"types commands"| node_control_page
node_control_page -->|"sends transcripts"| node_server
node_server -->|"sends state and events"| node_control_page
node_server -->|"forwards commands"| node_controller
node_controller -->|"requests interpretation"| node_jev
node_jev -->|"extracts candidates"| node_spans
node_jev -->|"builds questions"| node_constants
node_jev -->|"sends typed questions"| node_jev_service
node_jev_service -->|"returns answers"| node_jev
node_controller -->|"evaluates answers"| node_policy
node_policy -->|"normalizes URLs"| node_spans
node_policy -->|"uses thresholds"| node_constants
node_controller -->|"requests page state"| node_browser_manager
node_browser_manager -->|"builds snapshot"| node_snapshot
node_browser_manager -->|"controls pages and tabs"| node_chromium
node_controller -->|"dispatches actions"| node_executor
node_executor -->|"operates active page"| node_browser_manager
node_browser_manager -->|"invokes page feedback"| node_overlay
node_overlay -->|"renders highlights and prompts"| node_chromium

click node_control_page "https://github.com/moritzkremb/jev-voice-browser/blob/main/src/public/index.html"
click node_server "https://github.com/moritzkremb/jev-voice-browser/blob/main/src/server.js"
click node_controller "https://github.com/moritzkremb/jev-voice-browser/blob/main/src/controller.js"
click node_jev "https://github.com/moritzkremb/jev-voice-browser/blob/main/src/jev.js"
click node_policy "https://github.com/moritzkremb/jev-voice-browser/blob/main/src/policy.js"
click node_spans "https://github.com/moritzkremb/jev-voice-browser/blob/main/src/spans.js"
click node_constants "https://github.com/moritzkremb/jev-voice-browser/blob/main/src/constants.js"
click node_browser_manager "https://github.com/moritzkremb/jev-voice-browser/blob/main/src/browser.js"
click node_snapshot "https://github.com/moritzkremb/jev-voice-browser/blob/main/src/snapshot.js"
click node_executor "https://github.com/moritzkremb/jev-voice-browser/blob/main/src/executor.js"
click node_overlay "https://github.com/moritzkremb/jev-voice-browser/blob/main/src/overlay.js"

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_control_page,node_server,node_user toneBlue
class node_controller,node_jev,node_policy,node_spans,node_constants toneAmber
class node_browser_manager,node_snapshot,node_executor,node_overlay toneMint
class node_speech,node_jev_service,node_chromium toneRose
class node_microphone toneIndigo
```

## Components

### User interface

- [Control page](https://github.com/moritzkremb/jev-voice-browser/blob/main/src/public/index.html): `src/public/index.html`
- [HTTP and WS server](https://github.com/moritzkremb/jev-voice-browser/blob/main/src/server.js): `src/server.js`

### Interpretation and policy

- [Command controller](https://github.com/moritzkremb/jev-voice-browser/blob/main/src/controller.js): `src/controller.js`
- [Jev request builder](https://github.com/moritzkremb/jev-voice-browser/blob/main/src/jev.js): `src/jev.js`
- [Decision policy](https://github.com/moritzkremb/jev-voice-browser/blob/main/src/policy.js): `src/policy.js`
- [Candidate spans](https://github.com/moritzkremb/jev-voice-browser/blob/main/src/spans.js): `src/spans.js`
- [Questions and thresholds](https://github.com/moritzkremb/jev-voice-browser/blob/main/src/constants.js): `src/constants.js`

### Browser interaction

- [Browser manager](https://github.com/moritzkremb/jev-voice-browser/blob/main/src/browser.js): `src/browser.js`
- [Page snapshot](https://github.com/moritzkremb/jev-voice-browser/blob/main/src/snapshot.js): `src/snapshot.js`
- [Action executor](https://github.com/moritzkremb/jev-voice-browser/blob/main/src/executor.js): `src/executor.js`
- [Page feedback overlay](https://github.com/moritzkremb/jev-voice-browser/blob/main/src/overlay.js): `src/overlay.js`

### External services

- **Web Speech API**
- **TypeSafe Jev**
- **Playwright Chromium**

### Other components

- **User**
- **Microphone**

## Connections

- User → Microphone: speaks into
- Microphone → Web Speech API: captures audio
- Web Speech API → Control page: transcribes speech
- User → Control page: types commands
- Control page → HTTP and WS server: sends transcripts
- HTTP and WS server → Control page: sends state and events
- HTTP and WS server → Command controller: forwards commands
- Command controller → Jev request builder: requests interpretation
- Jev request builder → Candidate spans: extracts candidates
- Jev request builder → Questions and thresholds: builds questions
- Jev request builder → TypeSafe Jev: sends typed questions
- TypeSafe Jev → Jev request builder: returns answers
- Command controller → Decision policy: evaluates answers
- Decision policy → Candidate spans: normalizes URLs
- Decision policy → Questions and thresholds: uses thresholds
- Command controller → Browser manager: requests page state
- Browser manager → Page snapshot: builds snapshot
- Browser manager → Playwright Chromium: controls pages and tabs
- Command controller → Action executor: dispatches actions
- Action executor → Browser manager: operates active page
- Browser manager → Page feedback overlay: invokes page feedback
- Page feedback overlay → Playwright Chromium: renders highlights and prompts