# Tanuki Technical Architecture & Developer Specification (llms-full.txt)

## Executive Summary
Tanuki is an open-source browser automation runtime designed specifically for AI agent workflows. While traditional headless automation solutions fail when encountering MFA, complex single-sign-on (SSO), bot challenges (Cloudflare Turnstile, reCAPTCHA), or dynamic Single Page Application (SPA) DOM changes, Tanuki provides:
1. An ephemeral remote browser sandbox executed inside Docker containers or on Kubernetes.
2. Bidirectional CDP/WebRTC/SSE streaming allowing human-in-the-loop takeover when manual authorization or biometric MFA is required.
3. Self-healing path optimization that remembers selector paths across user tenants and automatically falls back to LLM DOM reasoning if selectors change.
4. Safe extraction of API keys, bearer tokens, or webhook credentials directly to Shuffle's encrypted datastore.

## System Architecture

```
+-------------------------------------------------------------------+
|                        Client Application                         |
|   (Web App / Next.js / React / AI Agent / Shuffle Workflow)       |
+---------------------------------+---------------------------------+
                                  |
               @shuffler/tanuki SDK (Iframe Modal / REST API)
                                  |
                                  v
+-------------------------------------------------------------------+
|                       Tanuki Server Engine                        |
|  - REST & SSE Gateway (/api/v1/sessions)                          |
|  - GoalEngine (Step Planner: connect -> auth -> locate -> extract)|
|  - LoginNavigator (Candidate scoring & OAuth popup handling)      |
|  - PathOptimizer (Multi-tier cache + LLM DOM element discovery)   |
|  - Security SessionVault (Encrypted in-memory token transit)      |
+---------------------------------+---------------------------------+
                                  |
                 Chrome DevTools Protocol (CDP) / WebSocket
                                  |
                                  v
+-------------------------------------------------------------------+
|                     Remote Browser Sandbox                        |
|  - Headless/Headed Chromium Container                             |
|  - Stealth evasion & Anti-Bot masks                               |
|  - Auto-dismiss Cookie Consent (CMP) in Shadow DOM                |
|  - CDP screencasting (JPEG/WebP 30 FPS) + Input Injection         |
+-------------------------------------------------------------------+
```

## REST API Endpoints

### 1. `POST /api/v1/sessions`
Initializes a new automation session.
- **Request Body**:
  ```json
  {
    "targetUrl": "https://github.com/settings/tokens",
    "goal": "get_api_key",
    "action": "get_api_key",
    "service": "github",
    "backendUrl": "https://uk.shuffler.io",
    "apiKey": "optional_shuffle_api_key",
    "authToken": "optional_bearer_token"
  }
  ```
- **Response (200 OK)**:
  ```json
  {
    "sessionId": "4a1c5d9e-8b2f-4107-b673-981cf05e4681",
    "status": "initializing",
    "streamUrl": "/api/v1/sessions/4a1c5d9e-8b2f-4107-b673-981cf05e4681/events"
  }
  ```

### 2. `GET /api/v1/sessions/:id`
Retrieves live status, plan execution state, and extracted results.
- **Response**:
  ```json
  {
    "sessionId": "4a1c5d9e-8b2f-4107-b673-981cf05e4681",
    "status": "completed",
    "plan": {
      "id": "plan_default",
      "steps": [
        { "id": "step_connect", "title": "Connect to remote secure browser", "status": "completed" },
        { "id": "step_auth", "title": "Sign in to your account", "status": "completed" },
        { "id": "step_locate", "title": "Locate API credentials", "status": "completed" },
        { "id": "step_extract", "title": "Extract API details & save", "status": "completed" }
      ]
    },
    "result": {
      "apiKey": "ghp_xxxxxxxxxxxxxxxxxxxx"
    }
  }
  ```

### 3. `GET /api/v1/sessions/:id/events`
Real-time Server-Sent Events (SSE) telemetry stream emitting logs, screencast frames, and status transitions.

### 4. `DELETE /api/v1/sessions/:id`
Closes the session immediately, aborts in-flight browser actions, and destroys the Playwright page context.

## Self-Healing Path Optimization (PathOptimizer)
1. **Tier 1 (Instant Local Cache)**: Look up domain + goal in high-speed LRU memory.
2. **Tier 2 (Shuffle Datastore Cache)**: Query Shuffle Datastore `/api/v2/tanuki_paths/{domain}__{goal}`.
3. **Tier 3 (Heuristic Login Navigation)**: Candidate scoring of visible DOM anchor/button elements matching localized login phrases.
4. **Tier 4 (LLM DOM Discovery)**: Dynamic LLM reasoning selecting the best interactive selector candidate.
5. **Auto-Healing**: Consecutive failures invalidate outdated selectors, triggering automated re-learning.

## Contact & Resources
- Web: https://tanuki.to
- Docs: https://tanuki.to/demo
- Organization: Shuffle Inc. (https://shuffler.io)
- Source Code: https://github.com/shuffle/tanuki