# krex381/openbrowse architecture

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

- Interactive diagram: https://gitdiagram.com/krex381/openbrowse
- Repository: https://github.com/krex381/openbrowse

## Overview

#### Purpose and Runtime

OpenBrowse is a self-hosted Node.js (>=24) service for authenticated web retrieval and browser automation. It uses direct HTTP first, escalating to sandboxed Chromium only when rendering or browser-only outputs are needed. Service startup is rooted at `src/index.ts`, with HTTP server composition in `src/server.ts` and `src/server/lifecycle.ts`.

#### API Edge and Interface Adapters

The server exposes native REST endpoints for fetch, render, extraction, artifacts, jobs, and owned sessions. Request parsing, authentication, validation, and route dispatch form the main trust boundary:
- `src/server.ts`
- `src/server/input.ts`
- `src/server/routes/execution.ts`

Optional Browserless-compatible, BrowserQL, MCP, and CDP reconnect surfaces adapt into the same execution core rather than owning separate browser pipelines:
- `src/server/browserql-handler.ts`
- `src/server/mcp.ts`
- `src/server/routes/cdp-reconnect.ts`

#### Policy and Security Boundary

Before fetch or navigation, the service applies API-key ownership, target validation, and network-target policy, including rejection of private, loopback, metadata, and DNS-resolved internal addresses. Security configuration and policy enforcement are concentrated in:
- `src/security.ts`
- `src/config/policies.ts`
- `src/server/input/validation.ts`

This is application-layer defense; deployment still requires DNS-aware egress enforcement. Raw CDP bridges and other high-risk capabilities are operator-controlled.

#### Execution Routing and Outputs

The execution core accepts normalized requests, chooses HTTP-only or browser execution, applies typed waits, and produces bounded HTML, Markdown, links, media, and extraction results. HTTP-first auto mode can detect client-rendered shells and escalate to Chromium:
- `src/execution.ts`
- `src/execution/http.ts`
- `src/execution/workflow.ts`

Content transformation and output-specific handling are separated from routing:
- `src/execution/markdown.ts`
- `src/execution/media.ts`
- `src/execution/content.ts`

#### Browser Workers, Sessions, and Admission Control

Browser work is managed as bounded pooled execution contexts with session lifecycle, queueing, process-memory admission, health/draining, and reconnect support. This separates externally visible session ownership from Chromium process management:
- `src/execution/pool.ts`
- `src/execution/sessions.ts`
- `src/queue.ts`

Chromium/CDP integration and recovery reside in:
- `src/cdp.ts`
- `src/cdp-reconnect.ts`
- `src/process-memory.ts`

#### Persistent Owned State

SQLite-backed storage persists API-key-scoped sessions, browser profiles, jobs, artifacts, proxies, handoffs, and operational records. Sensitive persisted state, including profiles and proxy credentials, is encrypted:
- `src/storage/database.ts`
- `src/storage/crypto.ts`
- `src/storage/sessions.ts`

Artifacts and queued/background work have dedicated persistence boundaries:
- `src/storage/artifacts.ts`
- `src/storage/jobs.ts`
- `src/storage/operations.ts`

The default SQLite one-writer model drives the single-replica Kubernetes deployment assumption.

#### Deployment and Client Surface

Production packaging runs Chromium in Docker with sandboxing, non-root execution, read-only filesystem, dropped capabilities, resource limits, and a seccomp profile:
- `Dockerfile`
- `docker-compose.yml`
- `deploy/seccomp_profile.json`

Kubernetes deployment is intentionally single replica and expects external egress controls:
- `deploy/kubernetes/openbrowse.yaml`
- `deploy/kubernetes/README.md`

A separate Vite/React landing and local viewer UI is served as a client surface, not the execution authority:
- `frontend/landing/src/main.tsx`
- `frontend/landing/src/app.tsx`
- `frontend/landing/src/components/workbench.tsx`

Main entry points: [`src/execution.ts`](https://github.com/krex381/openbrowse/blob/main/src/execution.ts) (Execution router), [`src/server.ts`](https://github.com/krex381/openbrowse/blob/main/src/server.ts) (HTTP server), [`src/queue.ts`](https://github.com/krex381/openbrowse/blob/main/src/queue.ts) (Admission queue), [`src/execution/pool.ts`](https://github.com/krex381/openbrowse/blob/main/src/execution/pool.ts) (Browser pool)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API Boundary"]
  node_startup["Service startup<br/>Node entrypoint<br/>[index.ts]"]
  node_http_server["HTTP server<br/>server composition<br/>[server.ts]"]
  node_api_routes["REST execution routes<br/>trust boundary<br/>[execution.ts]"]
  node_input["Request input<br/>parser<br/>[input.ts]"]
  node_adapters["Compatibility adapters"]
end

subgraph group_core["Execution Core"]
  node_policy{{"Target security policy<br/>validation and egress policy<br/>[security.ts]"}}
  node_execution["Execution router<br/>HTTP-first workflow<br/>[execution.ts]"]
  node_http_fetch["Direct HTTP retrieval<br/>HTTP executor<br/>[http.ts]"]
  node_outputs["Content outputs<br/>[content.ts]"]
end

subgraph group_browser["Browser Runtime"]
  node_admission_queue["Admission queue<br/>bounded work queue<br/>[queue.ts]"]
  node_browser_pool["Browser pool<br/>pooled execution contexts<br/>[pool.ts]"]
  node_owned_sessions["Owned sessions<br/>session lifecycle<br/>[sessions.ts]"]
  node_chromium_cdp["Chromium CDP<br/>browser integration<br/>[cdp.ts]"]
end

subgraph group_state["Persistent State"]
  node_sqlite[("SQLite database<br/>encrypted persistent store<br/>[database.ts]")]
  node_stored_sessions["Persisted sessions &amp; profiles<br/>encrypted state<br/>[sessions.ts]"]
  node_jobs_artifacts["Jobs &amp; artifacts<br/>persistent work records<br/>[jobs.ts]"]
end

subgraph group_operations["Deployment &amp; Client"]
  node_container["Hardened container<br/>Docker Chromium runtime"]
  node_kubernetes["Single-replica Kubernetes<br/>deployment manifest<br/>[openbrowse.yaml]"]
  node_viewer["Landing &amp; local viewer<br/>Vite/React client<br/>[main.tsx]"]
end

node_startup -->|"starts"| node_http_server
node_http_server -->|"serves"| node_api_routes
node_api_routes -->|"parses requests"| node_input
node_input -->|"validated target"| node_policy
node_policy -->|"authorized request"| node_execution
node_adapters -->|"shared execution API"| node_execution
node_execution -->|"HTTP-first path"| node_http_fetch
node_http_fetch -.->|"render-shell escalation"| node_execution
node_execution -->|"browser-required work"| node_admission_queue
node_admission_queue -->|"admitted work"| node_browser_pool
node_browser_pool -->|"controls"| node_chromium_cdp
node_owned_sessions -->|"leases contexts"| node_browser_pool
node_execution -->|"raw results"| node_outputs
node_owned_sessions -->|"persists ownership"| node_stored_sessions
node_stored_sessions -->|"stores"| node_sqlite
node_jobs_artifacts -->|"stores"| node_sqlite
node_admission_queue -.->|"durable work"| node_jobs_artifacts
node_container -->|"packages runtime"| node_http_server
node_kubernetes -->|"deploys"| node_container
node_viewer -->|"uses API"| node_http_server

click node_startup "https://github.com/krex381/openbrowse/blob/main/src/index.ts"
click node_http_server "https://github.com/krex381/openbrowse/blob/main/src/server.ts"
click node_api_routes "https://github.com/krex381/openbrowse/blob/main/src/server/routes/execution.ts"
click node_input "https://github.com/krex381/openbrowse/blob/main/src/server/input.ts"
click node_adapters "https://github.com/krex381/openbrowse/blob/main/src/server/browserql-handler.ts"
click node_policy "https://github.com/krex381/openbrowse/blob/main/src/security.ts"
click node_execution "https://github.com/krex381/openbrowse/blob/main/src/execution.ts"
click node_http_fetch "https://github.com/krex381/openbrowse/blob/main/src/execution/http.ts"
click node_outputs "https://github.com/krex381/openbrowse/blob/main/src/execution/content.ts"
click node_admission_queue "https://github.com/krex381/openbrowse/blob/main/src/queue.ts"
click node_browser_pool "https://github.com/krex381/openbrowse/blob/main/src/execution/pool.ts"
click node_owned_sessions "https://github.com/krex381/openbrowse/blob/main/src/execution/sessions.ts"
click node_chromium_cdp "https://github.com/krex381/openbrowse/blob/main/src/cdp.ts"
click node_sqlite "https://github.com/krex381/openbrowse/blob/main/src/storage/database.ts"
click node_stored_sessions "https://github.com/krex381/openbrowse/blob/main/src/storage/sessions.ts"
click node_jobs_artifacts "https://github.com/krex381/openbrowse/blob/main/src/storage/jobs.ts"
click node_container "https://github.com/krex381/openbrowse/blob/main/Dockerfile"
click node_kubernetes "https://github.com/krex381/openbrowse/blob/main/deploy/kubernetes/openbrowse.yaml"
click node_viewer "https://github.com/krex381/openbrowse/blob/main/frontend/landing/src/main.tsx"

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_startup,node_http_server,node_api_routes,node_input,node_adapters toneBlue
class node_policy,node_execution,node_http_fetch,node_outputs toneAmber
class node_admission_queue,node_browser_pool,node_owned_sessions,node_chromium_cdp toneMint
class node_sqlite,node_stored_sessions,node_jobs_artifacts toneRose
class node_container,node_kubernetes,node_viewer toneIndigo
```

## Components

### API Boundary

Authenticated request and adapter surfaces.

- [Service startup](https://github.com/krex381/openbrowse/blob/main/src/index.ts): Node entrypoint · `src/index.ts`
- [HTTP server](https://github.com/krex381/openbrowse/blob/main/src/server.ts): server composition · `src/server.ts`
- [REST execution routes](https://github.com/krex381/openbrowse/blob/main/src/server/routes/execution.ts): trust boundary · Parses, authenticates, validates, and dispatches requests. · `src/server/routes/execution.ts`
- [Request input](https://github.com/krex381/openbrowse/blob/main/src/server/input.ts): parser · `src/server/input.ts`
- [Compatibility adapters](https://github.com/krex381/openbrowse/blob/main/src/server/browserql-handler.ts): Browserless / BrowserQL / MCP / CDP · Adapt external protocols into the shared execution core. · `src/server/browserql-handler.ts`

### Execution Core

Policy, routing, and result generation.

- [Target security policy](https://github.com/krex381/openbrowse/blob/main/src/security.ts): validation and egress policy · Rejects private, loopback, metadata, and resolved internal targets. · `src/security.ts`
- [Execution router](https://github.com/krex381/openbrowse/blob/main/src/execution.ts): HTTP-first workflow · Selects HTTP or browser execution and may escalate rendered shells. · `src/execution.ts`
- [Direct HTTP retrieval](https://github.com/krex381/openbrowse/blob/main/src/execution/http.ts): HTTP executor · `src/execution/http.ts`
- [Content outputs](https://github.com/krex381/openbrowse/blob/main/src/execution/content.ts): HTML / Markdown / media · Builds bounded extraction and output-specific results. · `src/execution/content.ts`

### Browser Runtime

Bounded Chromium execution and session control.

- [Admission queue](https://github.com/krex381/openbrowse/blob/main/src/queue.ts): bounded work queue · Coordinates queued browser work and capacity. · `src/queue.ts`
- [Browser pool](https://github.com/krex381/openbrowse/blob/main/src/execution/pool.ts): pooled execution contexts · Manages health, draining, and process-memory admission. · `src/execution/pool.ts`
- [Owned sessions](https://github.com/krex381/openbrowse/blob/main/src/execution/sessions.ts): session lifecycle · Separates API-key session ownership from Chromium processes. · `src/execution/sessions.ts`
- [Chromium CDP](https://github.com/krex381/openbrowse/blob/main/src/cdp.ts): browser integration · Handles browser control, recovery, and reconnect. · `src/cdp.ts`

### Persistent State

Encrypted SQLite-owned operational data.

- [SQLite database](https://github.com/krex381/openbrowse/blob/main/src/storage/database.ts): encrypted persistent store · Single-writer store for API-key-scoped operational state. · `src/storage/database.ts`
- [Persisted sessions & profiles](https://github.com/krex381/openbrowse/blob/main/src/storage/sessions.ts): encrypted state · Stores sessions, profiles, and sensitive proxy data. · `src/storage/sessions.ts`
- [Jobs & artifacts](https://github.com/krex381/openbrowse/blob/main/src/storage/jobs.ts): persistent work records · Persists queued jobs, artifacts, and operations. · `src/storage/jobs.ts`

### Deployment & Client

Packaging, deployment, and separate viewer surface.

- [Hardened container](https://github.com/krex381/openbrowse/blob/main/Dockerfile): Docker Chromium runtime · Runs non-root Chromium with sandboxing and restricted filesystem/capabilities. · `Dockerfile`
- [Single-replica Kubernetes](https://github.com/krex381/openbrowse/blob/main/deploy/kubernetes/openbrowse.yaml): deployment manifest · Uses one replica for SQLite and relies on external egress controls. · `deploy/kubernetes/openbrowse.yaml`
- [Landing & local viewer](https://github.com/krex381/openbrowse/blob/main/frontend/landing/src/main.tsx): Vite/React client · Client surface only; it is not the execution authority. · `frontend/landing/src/main.tsx`

## Connections

- Service startup → HTTP server: starts
- HTTP server → REST execution routes: serves
- REST execution routes → Request input: parses requests
- Request input → Target security policy: validated target
- Target security policy → Execution router: authorized request
- Compatibility adapters → Execution router: shared execution API
- Execution router → Direct HTTP retrieval: HTTP-first path
- Direct HTTP retrieval → Execution router: render-shell escalation
- Execution router → Admission queue: browser-required work
- Admission queue → Browser pool: admitted work
- Browser pool → Chromium CDP: controls
- Owned sessions → Browser pool: leases contexts
- Execution router → Content outputs: raw results
- Owned sessions → Persisted sessions & profiles: persists ownership
- Persisted sessions & profiles → SQLite database: stores
- Jobs & artifacts → SQLite database: stores
- Admission queue → Jobs & artifacts: durable work
- Hardened container → HTTP server: packages runtime
- Single-replica Kubernetes → Hardened container: deploys
- Landing & local viewer → HTTP server: uses API