# steel-dev/steel-browser architecture

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

- Interactive diagram: https://gitdiagram.com/steel-dev/steel-browser
- Repository: https://github.com/steel-dev/steel-browser

## Overview

##### Main Components

a. Frontend Layer (UI):
- React-based web interface (/ui directory)
- Session management interface
- Debug console
- Session viewer
- WebSocket connections for real-time updates

b. Backend Layer (API):
- Fastify-based REST API server (/api directory)
- Multiple protocol support modules:
- CDP (Chrome DevTools Protocol)
- Selenium
- Puppeteer/Playwright integration

c. Browser Control Layer:
- Chrome browser instances
- Session management
- Extension system
- Proxy management

d. Integration Components:
- WebSocket connections
- REST API endpoints
- Browser automation protocols

##### Key Relationships to Highlight

- Client applications → REST API
- UI → WebSocket connections → Backend
- Backend → Browser instances
- Browser instances → External websites
- Proxy chain → Browser instances

##### Architectural Pattern Representation

Use a layered architecture approach:
**[External Clients/UI Layer]**
- ↓
**[API Gateway Layer (Fastify)]**
- ↓
**[Service Layer]**
- Session Service
- CDP Service
- Selenium Service
- ↓
**[Browser Control Layer]**
- ↓
**[External Resources (Websites/Proxies)]**

**[UI Components] → [WebSocket] → [Session Management]**
- ↓
**[REST API] → [Protocol Handlers (CDP/Selenium)] → [Browser Manager]**
- ↓
- [Chrome Instances]
- ↓
- [External Websites]

##### Additional Elements

- Extension system integration
- Proxy chain management
- Session recording capability
- Stealth plugin integration points
- Markdown/PDF conversion flow

##### Technical Details

- Port configurations (3000 for API)
- Protocol support (CDP, Selenium, Puppeteer)
- WebSocket connections for real-time updates
- Browser session management flow
- Extension loading paths

##### Implementation Notes

- The modular nature of the system
- Multiple protocol support
- Session isolation
- Real-time communication channels
- Resource management flows

- All major components
- Data flow directions
- Protocol boundaries
- Integration points
- Extension mechanisms

This system design should reflect Steel's architecture as a production-ready, containerized browser sandbox with emphasis on its core features: browser control, session management, proxy support, and debugging capabilities.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles and classes
    classDef frontend fill:#3498db,stroke:#2980b9,color:white
    classDef backend fill:#2ecc71,stroke:#27ae60,color:white
    classDef browser fill:#e67e22,stroke:#d35400,color:white
    classDef external fill:#95a5a6,stroke:#7f8c8d,color:white
    classDef integration fill:#9b59b6,stroke:#8e44ad,color:white
    classDef protocol fill:#f1c40f,stroke:#f39c12,color:black

    %% Frontend Layer
    subgraph Frontend
        UI["React UI App"]:::frontend
        SessionUI["Session Management UI"]:::frontend
        DebugConsole["Debug Console"]:::frontend
        SessionViewer["Session Viewer"]:::frontend
        WSClient["WebSocket Client"]:::frontend
    end

    %% Backend Layer
    subgraph Backend
        APIServer["Fastify API Server"]:::backend
        SessionMgmt["Session Management"]:::backend
        WSHandler["WebSocket Handler"]:::backend
        Routes["API Routes"]:::backend
        ActionCtrl["Action Controllers"]:::backend
    end

    %% Protocol Layer
    subgraph Protocols
        CDP["CDP Service"]:::protocol
        Selenium["Selenium Service"]:::protocol
        PuppeteerPlaywright["Puppeteer/Playwright"]:::protocol
    end

    %% Browser Control Layer
    subgraph BrowserControl
        BrowserMgr["Browser Manager"]:::browser
        SessionPlugin["Browser Session Plugin"]:::browser
        ExtSystem["Extension System"]:::browser
        ProxyMgmt["Proxy Management"]:::browser
    end

    %% External Resources
    ExternalSites["External Websites"]:::external
    Proxies["Proxy Servers"]:::external

    %% Relationships
    UI --> SessionUI
    UI --> DebugConsole
    UI --> SessionViewer
    UI --> WSClient
    WSClient --> WSHandler
    APIServer --> Routes
    Routes --> ActionCtrl
    ActionCtrl --> SessionMgmt
    SessionMgmt --> CDP
    SessionMgmt --> Selenium
    SessionMgmt --> PuppeteerPlaywright
    CDP --> BrowserMgr
    Selenium --> BrowserMgr
    PuppeteerPlaywright --> BrowserMgr
    BrowserMgr --> SessionPlugin
    BrowserMgr --> ExtSystem
    BrowserMgr --> ProxyMgmt
    ProxyMgmt --> Proxies
    SessionPlugin --> ExternalSites

    %% Click events
    click UI "https://github.com/steel-dev/steel-browser/blob/main/ui/src/App.tsx"
    click SessionUI "https://github.com/steel-dev/steel-browser/tree/main/ui/src/components/sessions"
    click DebugConsole "https://github.com/steel-dev/steel-browser/tree/main/ui/src/components/sessions/session-console"
    click SessionViewer "https://github.com/steel-dev/steel-browser/tree/main/ui/src/components/sessions/session-viewer"
    click WSClient "https://github.com/steel-dev/steel-browser/tree/main/ui/src/contexts/sessions-context"
    click APIServer "https://github.com/steel-dev/steel-browser/blob/main/api/src/build-server.ts"
    click CDP "https://github.com/steel-dev/steel-browser/tree/main/api/src/modules/cdp"
    click Selenium "https://github.com/steel-dev/steel-browser/tree/main/api/src/modules/selenium"
    click SessionMgmt "https://github.com/steel-dev/steel-browser/tree/main/api/src/modules/sessions"
    click BrowserMgr "https://github.com/steel-dev/steel-browser/blob/main/api/src/plugins/browser.ts"
    click SessionPlugin "https://github.com/steel-dev/steel-browser/blob/main/api/src/plugins/browser-session.ts"
    click ExtSystem "https://github.com/steel-dev/steel-browser/tree/main/api/extensions"
    click ProxyMgmt "https://github.com/steel-dev/steel-browser/blob/main/api/src/utils/proxy.ts"
    click WSHandler "https://github.com/steel-dev/steel-browser/blob/main/api/src/plugins/browser-socket.ts"
    click Routes "https://github.com/steel-dev/steel-browser/blob/main/api/src/routes.ts"
    click ActionCtrl "https://github.com/steel-dev/steel-browser/blob/main/api/src/modules/actions/actions.controller.ts"

    %% Legend
    subgraph Legend
        Frontend_L["Frontend Components"]:::frontend
        Backend_L["Backend Components"]:::backend
        Protocol_L["Protocol Services"]:::protocol
        Browser_L["Browser Components"]:::browser
        External_L["External Resources"]:::external
    end
```
