# ahansardar/veyra architecture

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

- Interactive diagram: https://gitdiagram.com/ahansardar/veyra
- Repository: https://github.com/ahansardar/veyra

## Overview

Veyra’s main workflow is a caller launching a Firefox-based browser through the Python API, which prepares a coherent session identity and browser options; the browser’s native patches apply masking while patched Juggler provides Playwright-compatible automation. The graph also preserves documented proxy-derived locale handling, add-ons, remote serving, virtual-display fallback, screencasting, and version management. Several implementation branches are represented from README claims because their source was not sampled; unverified wiring is omitted. The standalone jsonvv package is included because its substantial core modules are indexed.

Main entry points: [`pythonlib/veyra/utils.py`](https://github.com/ahansardar/veyra/blob/main/pythonlib/veyra/utils.py) (Launch options), [`pythonlib/veyra/fingerprints.py`](https://github.com/ahansardar/veyra/blob/main/pythonlib/veyra/fingerprints.py) (Fingerprint generation), [`jsonvv/jsonvv/validator.py`](https://github.com/ahansardar/veyra/blob/main/jsonvv/jsonvv/validator.py) (Type validator), [`pythonlib/veyra/async_api.py`](https://github.com/ahansardar/veyra/blob/main/pythonlib/veyra/async_api.py) (Async API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Python API"]
  node_sync["Sync API<br/>[sync_api.py]"]
  node_async["Async API<br/>[async_api.py]"]
  node_options["Launch options<br/>[utils.py]"]
  node_virtualdisplay["Virtual display<br/>[virtdisplay.py]"]
  node_addons["Add-on loading<br/>[addons.py]"]
  node_server["Remote server<br/>[server.py]"]
end

subgraph group_identity["Session identity"]
  node_identitygen["Fingerprint generation<br/>[fingerprints.py]"]
  node_geolocation["Proxy geolocation<br/>[geolocation.py]"]
  node_locales["Locale selection<br/>[locales.py]"]
  node_ip["IP resolution<br/>[ip.py]"]
  node_webgl["WebGL sampling<br/>[sample.py]"]
end

subgraph group_browser["Browser runtime"]
  node_maskconfig["Native mask config<br/>[MaskConfig.hpp]"]
  node_trajectories["Mouse trajectories"]
  node_juggler["Juggler automation<br/>[PageHandler.js]"]
  node_browserhandler["Browser protocol<br/>[BrowserHandler.js]"]
  node_screencast["Screencast service"]
end

subgraph group_management["Browser management"]
  node_pkgman["Version manager<br/>[pkgman.py]"]
  node_multiversion["Version channels<br/>[multiversion.py]"]
  node_gui["Browser manager UI<br/>[backend.py]"]
end

subgraph group_utilities["Libraries"]
  node_jsonparser["Type parser<br/>[parser.py]"]
  node_jsontypes["Type definitions<br/>[types.py]"]
  node_jsonvalidate["Type validator<br/>[validator.py]"]
  node_jsonstrings["String validation<br/>[strings.py]"]
  node_jsonexceptions["Parser exceptions<br/>[exceptions.py]"]
end

node_caller(("Automation caller"))

node_caller -->|"uses"| node_sync
node_caller -->|"uses"| node_async
node_sync -.->|"prepares launch"| node_options
node_async -.->|"prepares launch"| node_options
node_async -->|"uses"| node_identitygen
node_async -->|"uses"| node_virtualdisplay
node_identitygen -->|"loads data"| node_pkgman
node_identitygen -->|"uses"| node_locales
node_identitygen -->|"samples"| node_webgl
node_geolocation -->|"resolves"| node_ip
node_geolocation -->|"uses"| node_locales
node_options -->|"configures identity"| node_identitygen
node_options -.->|"passes settings"| node_maskconfig
node_options -.->|"loads add-ons"| node_addons
node_options -.->|"falls back to"| node_virtualdisplay
node_caller -->|"may launch"| node_server
node_server -->|"builds options"| node_options
node_caller -.->|"manages browser"| node_gui
node_gui -->|"manages versions"| node_pkgman
node_multiversion -->|"uses"| node_pkgman
node_maskconfig -->|"configures"| node_trajectories
node_juggler -.->|"protocol peers"| node_browserhandler
node_juggler -.->|"captures via"| node_screencast
node_jsonparser -->|"constructs types"| node_jsontypes
node_jsonparser -->|"validates strings"| node_jsonstrings
node_jsonparser -->|"raises"| node_jsonexceptions
node_jsonvalidate -->|"parses definitions"| node_jsonparser
node_jsonvalidate -->|"uses"| node_jsontypes
node_jsonvalidate -->|"validates strings"| node_jsonstrings
node_jsonvalidate -->|"raises"| node_jsonexceptions

click node_sync "https://github.com/ahansardar/veyra/blob/main/pythonlib/veyra/sync_api.py"
click node_async "https://github.com/ahansardar/veyra/blob/main/pythonlib/veyra/async_api.py"
click node_options "https://github.com/ahansardar/veyra/blob/main/pythonlib/veyra/utils.py"
click node_identitygen "https://github.com/ahansardar/veyra/blob/main/pythonlib/veyra/fingerprints.py"
click node_geolocation "https://github.com/ahansardar/veyra/blob/main/pythonlib/veyra/geolocation.py"
click node_locales "https://github.com/ahansardar/veyra/blob/main/pythonlib/veyra/locales.py"
click node_ip "https://github.com/ahansardar/veyra/blob/main/pythonlib/veyra/ip.py"
click node_webgl "https://github.com/ahansardar/veyra/blob/main/pythonlib/veyra/webgl/sample.py"
click node_maskconfig "https://github.com/ahansardar/veyra/blob/main/additions/veyracfg/MaskConfig.hpp"
click node_trajectories "https://github.com/ahansardar/veyra/blob/main/additions/veyracfg/MouseTrajectories.hpp"
click node_juggler "https://github.com/ahansardar/veyra/blob/main/additions/juggler/protocol/PageHandler.js"
click node_browserhandler "https://github.com/ahansardar/veyra/blob/main/additions/juggler/protocol/BrowserHandler.js"
click node_screencast "https://github.com/ahansardar/veyra/blob/main/additions/juggler/screencast/nsScreencastService.cpp"
click node_virtualdisplay "https://github.com/ahansardar/veyra/blob/main/pythonlib/veyra/virtdisplay.py"
click node_addons "https://github.com/ahansardar/veyra/blob/main/pythonlib/veyra/addons.py"
click node_server "https://github.com/ahansardar/veyra/blob/main/pythonlib/veyra/server.py"
click node_pkgman "https://github.com/ahansardar/veyra/blob/main/pythonlib/veyra/pkgman.py"
click node_multiversion "https://github.com/ahansardar/veyra/blob/main/pythonlib/veyra/multiversion.py"
click node_gui "https://github.com/ahansardar/veyra/blob/main/pythonlib/veyra/gui/backend.py"
click node_jsonparser "https://github.com/ahansardar/veyra/blob/main/jsonvv/jsonvv/parser.py"
click node_jsontypes "https://github.com/ahansardar/veyra/blob/main/jsonvv/jsonvv/types.py"
click node_jsonvalidate "https://github.com/ahansardar/veyra/blob/main/jsonvv/jsonvv/validator.py"
click node_jsonstrings "https://github.com/ahansardar/veyra/blob/main/jsonvv/jsonvv/strings.py"
click node_jsonexceptions "https://github.com/ahansardar/veyra/blob/main/jsonvv/jsonvv/exceptions.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_sync,node_async,node_options,node_virtualdisplay,node_addons,node_server toneBlue
class node_identitygen,node_geolocation,node_locales,node_ip,node_webgl toneAmber
class node_maskconfig,node_trajectories,node_juggler,node_browserhandler,node_screencast toneMint
class node_pkgman,node_multiversion,node_gui toneRose
class node_jsonparser,node_jsontypes,node_jsonvalidate,node_jsonstrings,node_jsonexceptions,node_caller toneIndigo
```

## Components

### Python API

- [Sync API](https://github.com/ahansardar/veyra/blob/main/pythonlib/veyra/sync_api.py): `pythonlib/veyra/sync_api.py`
- [Async API](https://github.com/ahansardar/veyra/blob/main/pythonlib/veyra/async_api.py): `pythonlib/veyra/async_api.py`
- [Launch options](https://github.com/ahansardar/veyra/blob/main/pythonlib/veyra/utils.py): `pythonlib/veyra/utils.py`
- [Virtual display](https://github.com/ahansardar/veyra/blob/main/pythonlib/veyra/virtdisplay.py): `pythonlib/veyra/virtdisplay.py`
- [Add-on loading](https://github.com/ahansardar/veyra/blob/main/pythonlib/veyra/addons.py): `pythonlib/veyra/addons.py`
- [Remote server](https://github.com/ahansardar/veyra/blob/main/pythonlib/veyra/server.py): `pythonlib/veyra/server.py`

### Session identity

- [Fingerprint generation](https://github.com/ahansardar/veyra/blob/main/pythonlib/veyra/fingerprints.py): `pythonlib/veyra/fingerprints.py`
- [Proxy geolocation](https://github.com/ahansardar/veyra/blob/main/pythonlib/veyra/geolocation.py): `pythonlib/veyra/geolocation.py`
- [Locale selection](https://github.com/ahansardar/veyra/blob/main/pythonlib/veyra/locales.py): `pythonlib/veyra/locales.py`
- [IP resolution](https://github.com/ahansardar/veyra/blob/main/pythonlib/veyra/ip.py): `pythonlib/veyra/ip.py`
- [WebGL sampling](https://github.com/ahansardar/veyra/blob/main/pythonlib/veyra/webgl/sample.py): `pythonlib/veyra/webgl/sample.py`

### Browser runtime

- [Native mask config](https://github.com/ahansardar/veyra/blob/main/additions/veyracfg/MaskConfig.hpp): `additions/veyracfg/MaskConfig.hpp`
- [Mouse trajectories](https://github.com/ahansardar/veyra/blob/main/additions/veyracfg/MouseTrajectories.hpp): `additions/veyracfg/MouseTrajectories.hpp`
- [Juggler automation](https://github.com/ahansardar/veyra/blob/main/additions/juggler/protocol/PageHandler.js): `additions/juggler/protocol/PageHandler.js`
- [Browser protocol](https://github.com/ahansardar/veyra/blob/main/additions/juggler/protocol/BrowserHandler.js): `additions/juggler/protocol/BrowserHandler.js`
- [Screencast service](https://github.com/ahansardar/veyra/blob/main/additions/juggler/screencast/nsScreencastService.cpp): `additions/juggler/screencast/nsScreencastService.cpp`

### Browser management

- [Version manager](https://github.com/ahansardar/veyra/blob/main/pythonlib/veyra/pkgman.py): `pythonlib/veyra/pkgman.py`
- [Version channels](https://github.com/ahansardar/veyra/blob/main/pythonlib/veyra/multiversion.py): `pythonlib/veyra/multiversion.py`
- [Browser manager UI](https://github.com/ahansardar/veyra/blob/main/pythonlib/veyra/gui/backend.py): `pythonlib/veyra/gui/backend.py`

### Libraries

- [Type parser](https://github.com/ahansardar/veyra/blob/main/jsonvv/jsonvv/parser.py): `jsonvv/jsonvv/parser.py`
- [Type definitions](https://github.com/ahansardar/veyra/blob/main/jsonvv/jsonvv/types.py): `jsonvv/jsonvv/types.py`
- [Type validator](https://github.com/ahansardar/veyra/blob/main/jsonvv/jsonvv/validator.py): `jsonvv/jsonvv/validator.py`
- [String validation](https://github.com/ahansardar/veyra/blob/main/jsonvv/jsonvv/strings.py): `jsonvv/jsonvv/strings.py`
- [Parser exceptions](https://github.com/ahansardar/veyra/blob/main/jsonvv/jsonvv/exceptions.py): `jsonvv/jsonvv/exceptions.py`

### Other components

- **Automation caller**

## Connections

- Automation caller → Sync API: uses
- Automation caller → Async API: uses
- Sync API → Launch options: prepares launch
- Async API → Launch options: prepares launch (evidence: `pythonlib/veyra/async_api.py`)
- Async API → Fingerprint generation: uses (evidence: `pythonlib/veyra/async_api.py`)
- Async API → Virtual display: uses (evidence: `pythonlib/veyra/async_api.py`)
- Fingerprint generation → Version manager: loads data (evidence: `pythonlib/veyra/fingerprints.py`)
- Fingerprint generation → Locale selection: uses (evidence: `pythonlib/veyra/fingerprints.py`)
- Fingerprint generation → WebGL sampling: samples (evidence: `pythonlib/veyra/fingerprints.py`)
- Proxy geolocation → IP resolution: resolves (evidence: `pythonlib/veyra/geolocation.py`)
- Proxy geolocation → Locale selection: uses (evidence: `pythonlib/veyra/geolocation.py`)
- Launch options → Fingerprint generation: configures identity (evidence: `pythonlib/veyra/utils.py`)
- Launch options → Native mask config: passes settings
- Launch options → Add-on loading: loads add-ons (evidence: `pythonlib/veyra/utils.py`)
- Launch options → Virtual display: falls back to (evidence: `pythonlib/veyra/utils.py`)
- Automation caller → Remote server: may launch (evidence: `pythonlib/veyra/server.py`)
- Remote server → Launch options: builds options (evidence: `pythonlib/veyra/server.py`)
- Automation caller → Browser manager UI: manages browser (evidence: `pythonlib/veyra/gui/backend.py`)
- Browser manager UI → Version manager: manages versions (evidence: `pythonlib/veyra/gui/backend.py`)
- Version channels → Version manager: uses (evidence: `pythonlib/veyra/multiversion.py`)
- Native mask config → Mouse trajectories: configures (evidence: `additions/veyracfg/MouseTrajectories.hpp`)
- Juggler automation → Browser protocol: protocol peers
- Juggler automation → Screencast service: captures via
- Type parser → Type definitions: constructs types (evidence: `jsonvv/jsonvv/parser.py`)
- Type parser → String validation: validates strings (evidence: `jsonvv/jsonvv/parser.py`)
- Type parser → Parser exceptions: raises (evidence: `jsonvv/jsonvv/parser.py`)
- Type validator → Type parser: parses definitions (evidence: `jsonvv/jsonvv/validator.py`)
- Type validator → Type definitions: uses (evidence: `jsonvv/jsonvv/validator.py`)
- Type validator → String validation: validates strings (evidence: `jsonvv/jsonvv/validator.py`)
- Type validator → Parser exceptions: raises (evidence: `jsonvv/jsonvv/validator.py`)
