# yashwant-das/ai-py-playwright-workbench architecture

> Architecture diagram of the GitHub repository yashwant-das/ai-py-playwright-workbench, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yashwant-das/ai-py-playwright-workbench
- Repository: https://github.com/yashwant-das/ai-py-playwright-workbench

## Overview

Playwright Workbench is a local web app for generating focused Playwright specs and healing failed specs with a local or Demo LLM. The main user flow starts in the browser UI, passes through guarded FastAPI routes and a single-run registry, then enters either the generation or healing pipeline. Generate captures page context before producing a spec; Heal gathers failure evidence, diagnoses and guards against suspected app defects, edits the spec, and retains a repair only after a passing rerun. Both workflows use model, browser-runner and saved-report layers. Unsampled route and storage wiring is represented only where documented or indexed.

Main entry points: [`src/workbench/heal/pipeline.py`](https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/heal/pipeline.py) (Guarded heal loop), [`src/workbench/generate/pipeline.py`](https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/generate/pipeline.py) (Spec generation), [`src/workbench/app.py`](https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/app.py) (FastAPI app), [`src/workbench/web/routes`](https://github.com/yashwant-das/ai-py-playwright-workbench/tree/main/src/workbench/web/routes) (Heal and Generate routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_app["FastAPI app<br/>[app.py]"]
  node_routes["Heal and Generate routes"]
  node_web_views["Pages and report views<br/>[views.py]"]
  node_web_services["Web service adapters<br/>[services.py]"]
  node_settings["Runtime configuration<br/>[config.py]"]
end

subgraph group_workflow["Test workflows"]
  node_generate["Spec generation<br/>[pipeline.py]"]
  node_heal["Guarded heal loop<br/>[pipeline.py]"]
  node_repair_plan["Repair planning<br/>[planner.py]"]
  node_repair["AST and text repair<br/>[repair.py]"]
  node_ast_script["TypeScript AST edits<br/>[ast_repair.js]"]
end

subgraph group_intelligence["Model and evidence"]
  node_context["Page context collection<br/>[collector.py]"]
  node_heal_evidence["Failure evidence<br/>[evidence.py]"]
  node_diagnosis["Failure diagnosis<br/>[classifier.py]"]
  node_llm["Chat model interface<br/>[chat.py]"]
  node_model_adapters["Provider and Demo clients<br/>[providers.py]"]
  node_contracts["Validated workflow contracts"]
end

subgraph group_runtime["Execution and results"]
  node_run_registry["Run registry and events<br/>[runs.py]"]
  node_runner["Playwright test runner<br/>[runner.py]"]
  node_reports[("Run reports and artifacts<br/>[reports.py]")]
end

node_browser(("Local browser UI"))
node_model_servers{{"Local model servers"}}
node_playwright{{"Playwright and Chromium"}}

node_browser -->|"uses"| node_app
node_app -->|"mounts routes"| node_routes
node_app -->|"creates registry"| node_run_registry
node_app -->|"configures services"| node_web_services
node_routes -->|"starts runs"| node_run_registry
node_routes -->|"dispatches workflows"| node_web_services
node_routes -->|"renders results"| node_web_views
node_web_services -->|"provides pipeline"| node_generate
node_web_services -->|"provides pipeline"| node_heal
node_generate -->|"collects context"| node_context
node_generate -->|"requests spec"| node_llm
node_generate -->|"optionally runs"| node_runner
node_generate -->|"saves report"| node_reports
node_heal -->|"runs and verifies"| node_runner
node_heal -->|"gathers evidence"| node_heal_evidence
node_heal -->|"classifies failure"| node_diagnosis
node_heal -->|"requests diagnosis"| node_llm
node_heal -->|"selects strategy"| node_repair_plan
node_heal -->|"applies repair"| node_repair
node_repair -->|"delegates AST edits"| node_ast_script
node_heal -->|"saves outcome"| node_reports
node_llm -.->|"uses providers"| node_model_adapters
node_model_adapters -.->|"calls local endpoint"| node_model_servers
node_generate -->|"builds report"| node_contracts
node_heal -->|"validates diagnosis"| node_contracts
node_runner -->|"executes spec"| node_playwright
node_runner -->|"reads run output"| node_reports
node_app -->|"loads configuration"| node_settings

click node_app "https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/app.py"
click node_routes "https://github.com/yashwant-das/ai-py-playwright-workbench/tree/main/src/workbench/web/routes"
click node_web_views "https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/web/views.py"
click node_web_services "https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/web/services.py"
click node_run_registry "https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/runs.py"
click node_generate "https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/generate/pipeline.py"
click node_heal "https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/heal/pipeline.py"
click node_context "https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/context/collector.py"
click node_heal_evidence "https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/heal/evidence.py"
click node_diagnosis "https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/heal/classifier.py"
click node_repair_plan "https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/heal/planner.py"
click node_repair "https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/heal/repair.py"
click node_ast_script "https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/heal/ast_repair.js"
click node_llm "https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/llm/chat.py"
click node_model_adapters "https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/llm/providers.py"
click node_contracts "https://github.com/yashwant-das/ai-py-playwright-workbench/tree/main/src/workbench/models"
click node_runner "https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/runner.py"
click node_reports "https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/reports.py"
click node_settings "https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/config.py"

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_app,node_routes,node_web_views,node_web_services,node_settings,node_browser toneBlue
class node_generate,node_heal,node_repair_plan,node_repair,node_ast_script toneAmber
class node_context,node_heal_evidence,node_diagnosis,node_llm,node_model_adapters,node_contracts,node_model_servers toneMint
class node_run_registry,node_runner,node_reports toneRose
class node_playwright toneIndigo
```

## Components

### Web application

- [FastAPI app](https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/app.py): `src/workbench/app.py`
- [Heal and Generate routes](https://github.com/yashwant-das/ai-py-playwright-workbench/tree/main/src/workbench/web/routes): `src/workbench/web/routes`
- [Pages and report views](https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/web/views.py): `src/workbench/web/views.py`
- [Web service adapters](https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/web/services.py): `src/workbench/web/services.py`
- [Runtime configuration](https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/config.py): `src/workbench/config.py`

### Test workflows

- [Spec generation](https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/generate/pipeline.py): `src/workbench/generate/pipeline.py`
- [Guarded heal loop](https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/heal/pipeline.py): `src/workbench/heal/pipeline.py`
- [Repair planning](https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/heal/planner.py): `src/workbench/heal/planner.py`
- [AST and text repair](https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/heal/repair.py): `src/workbench/heal/repair.py`
- [TypeScript AST edits](https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/heal/ast_repair.js): `src/workbench/heal/ast_repair.js`

### Model and evidence

- [Page context collection](https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/context/collector.py): `src/workbench/context/collector.py`
- [Failure evidence](https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/heal/evidence.py): `src/workbench/heal/evidence.py`
- [Failure diagnosis](https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/heal/classifier.py): `src/workbench/heal/classifier.py`
- [Chat model interface](https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/llm/chat.py): `src/workbench/llm/chat.py`
- [Provider and Demo clients](https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/llm/providers.py): `src/workbench/llm/providers.py`
- [Validated workflow contracts](https://github.com/yashwant-das/ai-py-playwright-workbench/tree/main/src/workbench/models): `src/workbench/models`

### Execution and results

- [Run registry and events](https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/runs.py): `src/workbench/runs.py`
- [Playwright test runner](https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/runner.py): `src/workbench/runner.py`
- [Run reports and artifacts](https://github.com/yashwant-das/ai-py-playwright-workbench/blob/main/src/workbench/reports.py): `src/workbench/reports.py`

### Other components

- **Local browser UI**
- **Local model servers**
- **Playwright and Chromium**

## Connections

- Local browser UI → FastAPI app: uses (evidence: `README.md`)
- FastAPI app → Heal and Generate routes: mounts routes (evidence: `src/workbench/app.py`)
- FastAPI app → Run registry and events: creates registry (evidence: `src/workbench/app.py`)
- FastAPI app → Web service adapters: configures services (evidence: `src/workbench/app.py`)
- Heal and Generate routes → Run registry and events: starts runs (evidence: `README.md`)
- Heal and Generate routes → Web service adapters: dispatches workflows (evidence: `src/workbench/web/routes/heal.py`)
- Heal and Generate routes → Pages and report views: renders results (evidence: `src/workbench/web/routes/heal.py`)
- Web service adapters → Spec generation: provides pipeline (evidence: `src/workbench/web/services.py`)
- Web service adapters → Guarded heal loop: provides pipeline (evidence: `src/workbench/web/services.py`)
- Spec generation → Page context collection: collects context (evidence: `src/workbench/generate/pipeline.py`)
- Spec generation → Chat model interface: requests spec (evidence: `src/workbench/generate/pipeline.py`)
- Spec generation → Playwright test runner: optionally runs (evidence: `README.md`)
- Spec generation → Run reports and artifacts: saves report (evidence: `src/workbench/generate/pipeline.py`)
- Guarded heal loop → Playwright test runner: runs and verifies (evidence: `src/workbench/heal/pipeline.py`)
- Guarded heal loop → Failure evidence: gathers evidence (evidence: `src/workbench/heal/pipeline.py`)
- Guarded heal loop → Failure diagnosis: classifies failure (evidence: `src/workbench/heal/pipeline.py`)
- Guarded heal loop → Chat model interface: requests diagnosis (evidence: `src/workbench/heal/pipeline.py`)
- Guarded heal loop → Repair planning: selects strategy (evidence: `src/workbench/heal/pipeline.py`)
- Guarded heal loop → AST and text repair: applies repair (evidence: `src/workbench/heal/pipeline.py`)
- AST and text repair → TypeScript AST edits: delegates AST edits (evidence: `src/workbench/heal/repair.py`)
- Guarded heal loop → Run reports and artifacts: saves outcome (evidence: `README.md`)
- Chat model interface → Provider and Demo clients: uses providers
- Provider and Demo clients → Local model servers: calls local endpoint
- Spec generation → Validated workflow contracts: builds report (evidence: `src/workbench/generate/pipeline.py`)
- Guarded heal loop → Validated workflow contracts: validates diagnosis (evidence: `src/workbench/heal/pipeline.py`)
- Playwright test runner → Playwright and Chromium: executes spec (evidence: `src/workbench/runner.py`)
- Playwright test runner → Run reports and artifacts: reads run output (evidence: `src/workbench/runner.py`)
- FastAPI app → Runtime configuration: loads configuration (evidence: `src/workbench/app.py`)