# browserbase/cua-browser architecture

> Architecture diagram of the GitHub repository browserbase/cua-browser, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/browserbase/cua-browser
- Repository: https://github.com/browserbase/cua-browser

## Overview

##### Project Type and Purpose
- The project is a demo playground (not a commercial product) that allows users to enter commands in natural language. The system then interacts with a browser via an agent that uses Browserbase for browser automation and OpenAI for generating instructions.
- It is a full-stack application built with Next.js (as indicated by the app directory structure and Next.js configuration files) that contains both frontend components (UI for user input and browser visualization) and backend API routes to process agent actions.

##### File Structure
- Top-Level Directories and Files:
– The “app” directory holds the Next.js pages, layout, globals.css, and route handlers, structured as modern Next.js 13 (app directory routing).
– The “app/api” directory contains several subdirectories (cua, session) structured to handle different API endpoints:
▪ The “agent” folder includes agent.ts, base_playwright.ts, browserbase.ts, and types.ts that form the core browser automation functionality.
▪ The “start” and “step” directories under “cua” likely provide endpoints for initializing agents and performing steps (like generating the action and executing it).
▪ The “session” endpoints manage browser sessions including page routing.
– The “components” directory holds React components used to render UI elements (such as ChatBlock, BrowserSessionContainer, and SessionControls) and provides a user interface for interacting with the agent.
– Supporting files such as configuration files (next.config.ts, tsconfig.json, vercel.json) and styling (globals.css, tailwind.config.ts) complete the setup.
- This division of folders shows a separation between backend API endpoints (handling the logic and communication with external services) and frontend UI components (rendering interactive components).

##### Architectural Insights from the README
- The README explains how the agent interacts with the browser: initializing a BrowserbaseBrowser instance, creating an Agent instance to interact with OpenAI’s API, and subsequently processing and executing commands.
- It highlights the methods “getAction” and “takeAction”, demonstrating the decoupling of decision-making (retrieving actions) and execution (performing browser operations).
- The example code gives insight into the flow from user input (via the frontend) through the agent API endpoint to the browser interaction.

## Diagram (Mermaid)

```mermaid
flowchart TD

  %% Frontend/UI Layer
  subgraph "Frontend/UI Layer"
    PL["Pages & Layout (Next.js)"]:::frontend
    UI["UI Components (React)"]:::frontend
  end

  %% Backend/API Layer
  subgraph "Backend/API Layer"
    S["API: Start Endpoint"]:::backend
    SG["API: Step - Generate Endpoint"]:::backend
    SE["API: Step - Execute Endpoint"]:::backend
    AG["API: Agent Logic"]:::backend
    SM["API: Session Management"]:::backend
  end

  %% External Services Layer
  subgraph "External Services"
    OA["OpenAI API"]:::external
    BB["Browserbase/Playwright"]:::external
  end

  %% Configuration Node
  CONF["Configuration & Setup"]:::config

  %% Data Flow Connections
  UI -->|"init"| S
  UI -->|"sendCommand"| SG
  S -->|"initAgent"| AG
  SG -->|"getAction"| AG
  AG -->|"prepareAction"| SE
  AG -->|"invoke_getAction"| OA
  SE -->|"takeAction"| BB
  BB -->|"sessionUpdate"| SM
  SM -->|"renderSession"| PL

  %% Dashed connection from configuration to layers
  CONF -.-> PL
  CONF -.-> UI
  CONF -.-> S
  CONF -.-> SG
  CONF -.-> SE
  CONF -.-> AG
  CONF -.-> SM

  %% Click Events for Component Mapping
  click PL "https://github.com/browserbase/cua-browser/blob/main/app/page.tsx"
  click UI "https://github.com/browserbase/cua-browser/tree/main/app/components"
  click AG "https://github.com/browserbase/cua-browser/tree/main/app/api/cua/agent"
  click S "https://github.com/browserbase/cua-browser/blob/main/app/api/cua/start/route.ts"
  click SG "https://github.com/browserbase/cua-browser/blob/main/app/api/cua/step/generate/route.ts"
  click SE "https://github.com/browserbase/cua-browser/blob/main/app/api/cua/step/execute/route.ts"
  click SM "https://github.com/browserbase/cua-browser/blob/main/app/api/session/route.ts"
  click CONF "https://github.com/browserbase/cua-browser/blob/main/next.config.ts"

  %% Styles
  classDef frontend fill:#f9e79f,stroke:#b9770e,stroke-width:2px;
  classDef backend fill:#aed6f1,stroke:#2471a3,stroke-width:2px;
  classDef external fill:#abebc6,stroke:#1d8348,stroke-width:2px;
  classDef config fill:#f5b7b1,stroke:#943126,stroke-width:2px;
```
