# oyadotai/oya-browser architecture

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

- Interactive diagram: https://gitdiagram.com/oyadotai/oya-browser
- Repository: https://github.com/oyadotai/oya-browser

## Overview

Oya is a browser automation product: users or agents start or connect a browser, ask it to perform work, inspect the result, and optionally save or replay that work as a playbook. The desktop app supplies a real, persistent browser; the server provides browser sessions, agent tools, identity and orchestration; SDK, CLI, and MCP are entry points. The README also documents routines, login/persona portability, CAPTCHA/MFA, and multiple browser providers. Some subsystem links are based on documented capabilities and tree paths because their source was not sampled.

Main entry points: [`server/src/modules/agent/loop.ts`](https://github.com/oyadotai/oya-browser/blob/main/server/src/modules/agent/loop.ts) (Agent task runner), [`server/src/modules/browsers/routes.ts`](https://github.com/oyadotai/oya-browser/blob/main/server/src/modules/browsers/routes.ts) (Browser routes), [`server/src/app/api.ts`](https://github.com/oyadotai/oya-browser/blob/main/server/src/app/api.ts) (HTTP API), [`server/src/modules/browsers/lifecycle`](https://github.com/oyadotai/oya-browser/tree/main/server/src/modules/browsers/lifecycle) (Browser lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client interfaces"]
  node_sdk["TypeScript SDK<br/>[index.ts]"]
  node_cli["CLI<br/>[index.ts]"]
  node_mcp["MCP tools<br/>[server.ts]"]
end

subgraph group_desktop["Desktop browser"]
  node_desktop_app["Desktop app<br/>[main.js]"]
  node_desktop_tabs["Tabs and pages<br/>[tabs.cjs]"]
  node_desktop_socket["Control socket<br/>[socket.cjs]"]
end

subgraph group_automation["Automation"]
  node_agent["Agent task runner<br/>[loop.ts]"]
  node_playbooks["Playbooks and runs<br/>[routes.ts]"]
  node_routines["Scheduled routines"]
  node_challenges["CAPTCHA and MFA"]
end

subgraph group_identity["Identity and access"]
  node_personas[("Personas and logins<br/>[service.ts]")]
  node_auth["Accounts and keys<br/>[routes.ts]"]
end

subgraph group_services["Browser services"]
  node_api["HTTP API<br/>[api.ts]"]
  node_browser_routes["Browser routes<br/>[routes.ts]"]
  node_browser_lifecycle["Browser lifecycle"]
  node_gateway["Session gateway"]
  node_browser_registry[("Browser registry<br/>[registry.ts]")]
  node_control["Control plane<br/>[service.ts]"]
  node_providers["Browser providers<br/>[providers.ts]"]
end

node_user(("User or agent"))
node_sites(("Websites"))
node_llm(("LLM service"))
node_slack(("Slack"))

node_user -->|"uses"| node_sdk
node_user -->|"configures"| node_cli
node_user -->|"invokes"| node_mcp
node_sdk -->|"sends requests"| node_api
node_cli -->|"configures access"| node_api
node_mcp -->|"calls tools"| node_api
node_api -->|"routes auth"| node_auth
node_api -->|"routes browser requests"| node_browser_routes
node_browser_routes -->|"starts and stops"| node_browser_lifecycle
node_browser_routes -->|"lists browsers"| node_browser_registry
node_browser_routes -->|"dispatches chat"| node_agent
node_browser_routes -->|"handles challenges"| node_challenges
node_browser_lifecycle -->|"establishes sessions"| node_gateway
node_browser_lifecycle -->|"selects provider"| node_providers
node_gateway -->|"connects browser"| node_desktop_socket
node_desktop_app -->|"owns connection"| node_desktop_socket
node_desktop_socket -->|"dispatches commands"| node_desktop_tabs
node_desktop_tabs -->|"navigates and acts"| node_sites
node_agent -->|"controls page"| node_desktop_tabs
node_agent -->|"requests reasoning"| node_llm
node_agent -->|"saves task"| node_playbooks
node_playbooks -->|"replays steps"| node_agent
node_user -->|"records workflow"| node_playbooks
node_user -->|"manages identity"| node_personas
node_personas -->|"supplies persona"| node_browser_lifecycle
node_auth -->|"scopes access"| node_personas
node_user -->|"schedules work"| node_routines
node_routines -->|"runs prompt"| node_agent
node_control -->|"coordinates capacity"| node_browser_lifecycle
node_control -.->|"sends alerts"| node_slack

click node_sdk "https://github.com/oyadotai/oya-browser/blob/main/packages/sdk/src/index.ts"
click node_cli "https://github.com/oyadotai/oya-browser/blob/main/packages/cli/src/index.ts"
click node_mcp "https://github.com/oyadotai/oya-browser/blob/main/server/src/mcp/server.ts"
click node_api "https://github.com/oyadotai/oya-browser/blob/main/server/src/app/api.ts"
click node_browser_routes "https://github.com/oyadotai/oya-browser/blob/main/server/src/modules/browsers/routes.ts"
click node_browser_lifecycle "https://github.com/oyadotai/oya-browser/tree/main/server/src/modules/browsers/lifecycle"
click node_gateway "https://github.com/oyadotai/oya-browser/tree/main/server/src/modules/gateway"
click node_browser_registry "https://github.com/oyadotai/oya-browser/blob/main/server/src/modules/browsers/registry.ts"
click node_desktop_app "https://github.com/oyadotai/oya-browser/blob/main/browser/main.js"
click node_desktop_tabs "https://github.com/oyadotai/oya-browser/blob/main/browser/main/tabs/tabs.cjs"
click node_desktop_socket "https://github.com/oyadotai/oya-browser/blob/main/browser/main/connection/socket.cjs"
click node_personas "https://github.com/oyadotai/oya-browser/blob/main/server/src/modules/personas/service.ts"
click node_auth "https://github.com/oyadotai/oya-browser/blob/main/server/src/modules/auth/routes.ts"
click node_agent "https://github.com/oyadotai/oya-browser/blob/main/server/src/modules/agent/loop.ts"
click node_playbooks "https://github.com/oyadotai/oya-browser/blob/main/server/src/modules/playbooks/routes.ts"
click node_routines "https://github.com/oyadotai/oya-browser/tree/main/server/src/modules/routines"
click node_challenges "https://github.com/oyadotai/oya-browser/tree/main/server/src/modules/challenges"
click node_control "https://github.com/oyadotai/oya-browser/blob/main/server/src/modules/control/service.ts"
click node_providers "https://github.com/oyadotai/oya-browser/blob/main/server/src/drivers/providers.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_sdk,node_cli,node_mcp,node_user toneBlue
class node_desktop_app,node_desktop_tabs,node_desktop_socket toneAmber
class node_agent,node_playbooks,node_routines,node_challenges toneMint
class node_personas,node_auth toneRose
class node_api,node_browser_routes,node_browser_lifecycle,node_gateway,node_browser_registry,node_control,node_providers,node_sites,node_llm,node_slack toneIndigo
```

## Components

### Client interfaces

- [TypeScript SDK](https://github.com/oyadotai/oya-browser/blob/main/packages/sdk/src/index.ts): `packages/sdk/src/index.ts`
- [CLI](https://github.com/oyadotai/oya-browser/blob/main/packages/cli/src/index.ts): `packages/cli/src/index.ts`
- [MCP tools](https://github.com/oyadotai/oya-browser/blob/main/server/src/mcp/server.ts): `server/src/mcp/server.ts`

### Desktop browser

- [Desktop app](https://github.com/oyadotai/oya-browser/blob/main/browser/main.js): `browser/main.js`
- [Tabs and pages](https://github.com/oyadotai/oya-browser/blob/main/browser/main/tabs/tabs.cjs): `browser/main/tabs/tabs.cjs`
- [Control socket](https://github.com/oyadotai/oya-browser/blob/main/browser/main/connection/socket.cjs): `browser/main/connection/socket.cjs`

### Automation

- [Agent task runner](https://github.com/oyadotai/oya-browser/blob/main/server/src/modules/agent/loop.ts): `server/src/modules/agent/loop.ts`
- [Playbooks and runs](https://github.com/oyadotai/oya-browser/blob/main/server/src/modules/playbooks/routes.ts): `server/src/modules/playbooks/routes.ts`
- [Scheduled routines](https://github.com/oyadotai/oya-browser/tree/main/server/src/modules/routines): `server/src/modules/routines`
- [CAPTCHA and MFA](https://github.com/oyadotai/oya-browser/tree/main/server/src/modules/challenges): `server/src/modules/challenges`

### Identity and access

- [Personas and logins](https://github.com/oyadotai/oya-browser/blob/main/server/src/modules/personas/service.ts): `server/src/modules/personas/service.ts`
- [Accounts and keys](https://github.com/oyadotai/oya-browser/blob/main/server/src/modules/auth/routes.ts): `server/src/modules/auth/routes.ts`

### Browser services

- [HTTP API](https://github.com/oyadotai/oya-browser/blob/main/server/src/app/api.ts): `server/src/app/api.ts`
- [Browser routes](https://github.com/oyadotai/oya-browser/blob/main/server/src/modules/browsers/routes.ts): `server/src/modules/browsers/routes.ts`
- [Browser lifecycle](https://github.com/oyadotai/oya-browser/tree/main/server/src/modules/browsers/lifecycle): `server/src/modules/browsers/lifecycle`
- [Session gateway](https://github.com/oyadotai/oya-browser/tree/main/server/src/modules/gateway): `server/src/modules/gateway`
- [Browser registry](https://github.com/oyadotai/oya-browser/blob/main/server/src/modules/browsers/registry.ts): `server/src/modules/browsers/registry.ts`
- [Control plane](https://github.com/oyadotai/oya-browser/blob/main/server/src/modules/control/service.ts): `server/src/modules/control/service.ts`
- [Browser providers](https://github.com/oyadotai/oya-browser/blob/main/server/src/drivers/providers.ts): `server/src/drivers/providers.ts`

### Other components

- **User or agent**
- **Websites**
- **LLM service**
- **Slack**

## Connections

- User or agent → TypeScript SDK: uses
- User or agent → CLI: configures
- User or agent → MCP tools: invokes
- TypeScript SDK → HTTP API: sends requests
- CLI → HTTP API: configures access
- MCP tools → HTTP API: calls tools
- HTTP API → Accounts and keys: routes auth
- HTTP API → Browser routes: routes browser requests
- Browser routes → Browser lifecycle: starts and stops
- Browser routes → Browser registry: lists browsers
- Browser routes → Agent task runner: dispatches chat
- Browser routes → CAPTCHA and MFA: handles challenges
- Browser lifecycle → Session gateway: establishes sessions
- Browser lifecycle → Browser providers: selects provider
- Session gateway → Control socket: connects browser
- Desktop app → Control socket: owns connection
- Control socket → Tabs and pages: dispatches commands
- Tabs and pages → Websites: navigates and acts
- Agent task runner → Tabs and pages: controls page
- Agent task runner → LLM service: requests reasoning
- Agent task runner → Playbooks and runs: saves task
- Playbooks and runs → Agent task runner: replays steps
- User or agent → Playbooks and runs: records workflow
- User or agent → Personas and logins: manages identity
- Personas and logins → Browser lifecycle: supplies persona
- Accounts and keys → Personas and logins: scopes access
- User or agent → Scheduled routines: schedules work
- Scheduled routines → Agent task runner: runs prompt
- Control plane → Browser lifecycle: coordinates capacity
- Control plane → Slack: sends alerts