# santosh1664/browserless-chromium architecture

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

- Interactive diagram: https://gitdiagram.com/santosh1664/browserless-chromium
- Repository: https://github.com/santosh1664/browserless-chromium

## Overview

Browserless is a browser-automation platform exposing HTTP and WebSocket interfaces for Chromium operations, including REST-style tasks, browser protocols, custom functions, and BrowserQL. A request enters the server and is routed to an operation; BrowserQL also supports GraphQL subscriptions over WebSocket. The tree shows management endpoints and browser backends as distinct product areas. Evidence is limited to the supplied excerpts and SOURCE INDEX; where runtime wiring was not shown, the graph preserves capabilities without guessing their call paths.

Main entry points: [`src/server.ts`](https://github.com/santosh1664/browserless-chromium/blob/main/src/server.ts) (HTTP and WS server), [`src/routes/chromium/http`](https://github.com/santosh1664/browserless-chromium/tree/main/src/routes/chromium/http) (Chromium HTTP routes), [`src/browsers/index.ts`](https://github.com/santosh1664/browserless-chromium/blob/main/src/browsers/index.ts) (Browser manager), [`src/bql/ws-session.ts`](https://github.com/santosh1664/browserless-chromium/blob/main/src/bql/ws-session.ts) (BrowserQL WebSocket)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Request interfaces"]
  node_server["HTTP and WS server<br/>[server.ts]"]
  node_chromium_http["Chromium HTTP routes"]
  node_chromium_ws["Chromium WS routes"]
  node_http_handlers["HTTP operation handlers"]
  node_function_handler["Function runner handler<br/>[handler.ts]"]
  node_function_client["In-browser function client<br/>[client.ts]"]
  node_schema_validator["Request schema validation"]
end

subgraph group_browser["Browser runtime"]
  node_browser_manager["Browser manager<br/>[index.ts]"]
  node_playwright_backend["Playwright backend"]
  node_cdp_backend["CDP backend<br/>[browsers.cdp.ts]"]
  node_network_security["Navigation security"]
end

subgraph group_bql["BrowserQL"]
  node_bql_http["BrowserQL HTTP<br/>[http.ts]"]
  node_bql_ws["BrowserQL WebSocket<br/>[ws-session.ts]"]
  node_bql_executor["BrowserQL executor<br/>[executor.ts]"]
  node_bql_api["BrowserQL browser API<br/>[browser-api.ts]"]
  node_bql_schema["GraphQL schema assembly<br/>[build.ts]"]
  node_bql_resolvers["BrowserQL resolvers"]
  node_bql_subscriptions["Event subscriptions<br/>[subscription.ts]"]
  node_bql_json["JSON serialization<br/>[json.ts]"]
  node_bql_patterns["BrowserQL patterns<br/>[patterns.ts]"]
end

subgraph group_ops["Platform operations"]
  node_management["Management endpoints"]
  node_config["Runtime configuration<br/>[config.ts]"]
  node_metrics["Metrics and monitoring<br/>[metrics.ts]"]
end

node_client(("API clients"))

node_client -.->|"sends requests"| node_server
node_server -->|"validates schemas"| node_schema_validator
node_server -.->|"routes HTTP"| node_chromium_http
node_server -.->|"routes WebSocket"| node_chromium_ws
node_chromium_http -.->|"dispatches operations"| node_http_handlers
node_chromium_http -.->|"dispatches functions"| node_function_handler
node_function_handler -->|"runs page code"| node_function_client
node_browser_manager -.->|"provides backend"| node_playwright_backend
node_browser_manager -.->|"provides backend"| node_cdp_backend
node_playwright_backend -->|"reads settings"| node_config
node_config -->|"uses policies"| node_network_security
node_bql_http -.->|"executes queries"| node_bql_executor
node_bql_ws -.->|"executes operations"| node_bql_executor
node_bql_ws -->|"formats messages"| node_bql_json
node_bql_api -->|"matches patterns"| node_bql_patterns
node_bql_schema -->|"registers resolvers"| node_bql_resolvers
node_bql_subscriptions -->|"streams browser events"| node_bql_api

click node_server "https://github.com/santosh1664/browserless-chromium/blob/main/src/server.ts"
click node_chromium_http "https://github.com/santosh1664/browserless-chromium/tree/main/src/routes/chromium/http"
click node_chromium_ws "https://github.com/santosh1664/browserless-chromium/tree/main/src/routes/chromium/ws"
click node_http_handlers "https://github.com/santosh1664/browserless-chromium/tree/main/src/shared"
click node_function_handler "https://github.com/santosh1664/browserless-chromium/blob/main/src/shared/utils/function/handler.ts"
click node_function_client "https://github.com/santosh1664/browserless-chromium/blob/main/src/shared/utils/function/client.ts"
click node_schema_validator "https://github.com/santosh1664/browserless-chromium/blob/main/src/shared/utils/schema-validator.ts"
click node_browser_manager "https://github.com/santosh1664/browserless-chromium/blob/main/src/browsers/index.ts"
click node_playwright_backend "https://github.com/santosh1664/browserless-chromium/blob/main/src/browsers/browsers.playwright.ts"
click node_cdp_backend "https://github.com/santosh1664/browserless-chromium/blob/main/src/browsers/browsers.cdp.ts"
click node_network_security "https://github.com/santosh1664/browserless-chromium/blob/main/src/network-security.ts"
click node_bql_http "https://github.com/santosh1664/browserless-chromium/blob/main/src/bql/http.ts"
click node_bql_ws "https://github.com/santosh1664/browserless-chromium/blob/main/src/bql/ws-session.ts"
click node_bql_executor "https://github.com/santosh1664/browserless-chromium/blob/main/src/bql/executor.ts"
click node_bql_api "https://github.com/santosh1664/browserless-chromium/blob/main/src/bql/api/browser-api.ts"
click node_bql_schema "https://github.com/santosh1664/browserless-chromium/blob/main/src/bql/schema/build.ts"
click node_bql_resolvers "https://github.com/santosh1664/browserless-chromium/tree/main/src/bql/schema/resolvers"
click node_bql_subscriptions "https://github.com/santosh1664/browserless-chromium/blob/main/src/bql/schema/resolvers/subscription.ts"
click node_bql_json "https://github.com/santosh1664/browserless-chromium/blob/main/src/bql/json.ts"
click node_management "https://github.com/santosh1664/browserless-chromium/tree/main/src/routes/management/http"
click node_config "https://github.com/santosh1664/browserless-chromium/blob/main/src/config.ts"
click node_metrics "https://github.com/santosh1664/browserless-chromium/blob/main/src/metrics.ts"
click node_bql_patterns "https://github.com/santosh1664/browserless-chromium/blob/main/src/bql/patterns.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_server,node_chromium_http,node_chromium_ws,node_http_handlers,node_function_handler,node_function_client,node_schema_validator,node_client toneBlue
class node_browser_manager,node_playwright_backend,node_cdp_backend,node_network_security toneAmber
class node_bql_http,node_bql_ws,node_bql_executor,node_bql_api,node_bql_schema,node_bql_resolvers,node_bql_subscriptions,node_bql_json,node_bql_patterns toneMint
class node_management,node_config,node_metrics toneRose
```

## Components

### Request interfaces

- [HTTP and WS server](https://github.com/santosh1664/browserless-chromium/blob/main/src/server.ts): `src/server.ts`
- [Chromium HTTP routes](https://github.com/santosh1664/browserless-chromium/tree/main/src/routes/chromium/http): `src/routes/chromium/http`
- [Chromium WS routes](https://github.com/santosh1664/browserless-chromium/tree/main/src/routes/chromium/ws): `src/routes/chromium/ws`
- [HTTP operation handlers](https://github.com/santosh1664/browserless-chromium/tree/main/src/shared): `src/shared`
- [Function runner handler](https://github.com/santosh1664/browserless-chromium/blob/main/src/shared/utils/function/handler.ts): `src/shared/utils/function/handler.ts`
- [In-browser function client](https://github.com/santosh1664/browserless-chromium/blob/main/src/shared/utils/function/client.ts): `src/shared/utils/function/client.ts`
- [Request schema validation](https://github.com/santosh1664/browserless-chromium/blob/main/src/shared/utils/schema-validator.ts): `src/shared/utils/schema-validator.ts`

### Browser runtime

- [Browser manager](https://github.com/santosh1664/browserless-chromium/blob/main/src/browsers/index.ts): `src/browsers/index.ts`
- [Playwright backend](https://github.com/santosh1664/browserless-chromium/blob/main/src/browsers/browsers.playwright.ts): `src/browsers/browsers.playwright.ts`
- [CDP backend](https://github.com/santosh1664/browserless-chromium/blob/main/src/browsers/browsers.cdp.ts): `src/browsers/browsers.cdp.ts`
- [Navigation security](https://github.com/santosh1664/browserless-chromium/blob/main/src/network-security.ts): `src/network-security.ts`

### BrowserQL

- [BrowserQL HTTP](https://github.com/santosh1664/browserless-chromium/blob/main/src/bql/http.ts): `src/bql/http.ts`
- [BrowserQL WebSocket](https://github.com/santosh1664/browserless-chromium/blob/main/src/bql/ws-session.ts): `src/bql/ws-session.ts`
- [BrowserQL executor](https://github.com/santosh1664/browserless-chromium/blob/main/src/bql/executor.ts): `src/bql/executor.ts`
- [BrowserQL browser API](https://github.com/santosh1664/browserless-chromium/blob/main/src/bql/api/browser-api.ts): `src/bql/api/browser-api.ts`
- [GraphQL schema assembly](https://github.com/santosh1664/browserless-chromium/blob/main/src/bql/schema/build.ts): `src/bql/schema/build.ts`
- [BrowserQL resolvers](https://github.com/santosh1664/browserless-chromium/tree/main/src/bql/schema/resolvers): `src/bql/schema/resolvers`
- [Event subscriptions](https://github.com/santosh1664/browserless-chromium/blob/main/src/bql/schema/resolvers/subscription.ts): `src/bql/schema/resolvers/subscription.ts`
- [JSON serialization](https://github.com/santosh1664/browserless-chromium/blob/main/src/bql/json.ts): `src/bql/json.ts`
- [BrowserQL patterns](https://github.com/santosh1664/browserless-chromium/blob/main/src/bql/patterns.ts): `src/bql/patterns.ts`

### Platform operations

- [Management endpoints](https://github.com/santosh1664/browserless-chromium/tree/main/src/routes/management/http): `src/routes/management/http`
- [Runtime configuration](https://github.com/santosh1664/browserless-chromium/blob/main/src/config.ts): `src/config.ts`
- [Metrics and monitoring](https://github.com/santosh1664/browserless-chromium/blob/main/src/metrics.ts): `src/metrics.ts`

### Other components

- **API clients**

## Connections

- API clients → HTTP and WS server: sends requests
- HTTP and WS server → Request schema validation: validates schemas (evidence: `src/server.ts`)
- HTTP and WS server → Chromium HTTP routes: routes HTTP
- HTTP and WS server → Chromium WS routes: routes WebSocket
- Chromium HTTP routes → HTTP operation handlers: dispatches operations
- Chromium HTTP routes → Function runner handler: dispatches functions
- Function runner handler → In-browser function client: runs page code (evidence: `src/shared/utils/function/handler.ts`)
- Browser manager → Playwright backend: provides backend
- Browser manager → CDP backend: provides backend
- Playwright backend → Runtime configuration: reads settings (evidence: `src/browsers/browsers.playwright.ts`)
- Runtime configuration → Navigation security: uses policies (evidence: `src/config.ts`)
- BrowserQL HTTP → BrowserQL executor: executes queries
- BrowserQL WebSocket → BrowserQL executor: executes operations
- BrowserQL WebSocket → JSON serialization: formats messages (evidence: `src/bql/ws-session.ts`)
- BrowserQL browser API → BrowserQL patterns: matches patterns (evidence: `src/bql/api/browser-api.ts`)
- GraphQL schema assembly → BrowserQL resolvers: registers resolvers (evidence: `src/bql/schema/build.ts`)
- Event subscriptions → BrowserQL browser API: streams browser events (evidence: `src/bql/schema/resolvers/subscription.ts`)
