> ## Documentation Index
> Fetch the complete documentation index at: https://docs.searchcompany.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Architecture and internal services for the Browser Session endpoints

## Purpose

Creates and manages Browserbase browser sessions for live website visualization on the marketing site. Shows visitors a real-time browser view of their website being "scanned".

## Architecture

```mermaid theme={null}
flowchart TD
    subgraph endpoints [Endpoints]
        Create["POST /api/browser-session"]
        Delete["DELETE /api/browser-session/{id}"]
    end
    
    subgraph services [Internal Services]
        CreateSession["_create_browserbase_session()"]
        Navigate["_navigate_in_background()"]
        ClientKey["_client_key()"]
    end
    
    subgraph external [External APIs]
        BB["Browserbase API"]
        PW["Playwright CDP"]
    end
    
    subgraph cache [In-Memory Cache]
        Sessions["_ACTIVE_SESSION_BY_CLIENT"]
        Tasks["_NAVIGATION_TASKS"]
    end
    
    Create --> ClientKey
    ClientKey --> Sessions
    Sessions -->|"Cache miss"| CreateSession
    CreateSession --> BB
    BB --> Navigate
    Navigate --> PW
    PW --> Tasks
    
    Delete --> Tasks
    Delete --> Sessions
    Delete --> BB
```

## Two-Phase Flow

1. **Pre-warm** - Create session without URL (fast, session ready)
2. **Navigate** - Send URL to existing session (navigation happens in background)

This allows the frontend to show the browser embed immediately while navigation loads.

## Internal Services

| Service                                                       | Purpose                                  |
| ------------------------------------------------------------- | ---------------------------------------- |
| [\_create\_browserbase\_session](_create-browserbase-session) | Creates session via Browserbase API      |
| [\_navigate\_in\_background](_navigate-in-background)         | Playwright navigation + scroll animation |
| [\_client\_key](_client-key)                                  | IP-based client identification           |

## Code Location

```
src/website/browser_session/
└── routes.py    # All logic in single file
```

## Session Caching

Sessions are cached per client IP + viewport width for 5 minutes. This prevents creating duplicate sessions for the same visitor.

## Scroll Animation

After navigation, the background task performs automated scrolling:

1. Wait 2 seconds
2. Smooth scroll down 1.5 viewport heights
3. Wait 5 seconds
4. Scroll down another viewport height

This creates a "scanning" visual effect.

## Rate Limiting

| Endpoint       | Limit     |
| -------------- | --------- |
| Create session | 60/minute |
| End session    | 10/minute |