# headout/autoheal architecture

> Architecture diagram of the GitHub repository headout/autoheal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/headout/autoheal
- Repository: https://github.com/headout/autoheal

## Overview

AutoHeal Locator is a Java library that heals broken Selenium and Playwright element locators. A test calls the public locator API; AutoHeal tries the original selector, checks cached fixes, then uses configured DOM, visual, or hybrid AI-backed strategies and returns a recovered element or locator. Framework adapters bridge to the browser automation APIs, while configuration, reporting, and monitoring support the runtime. The main entry-point excerpt was read in full; several subsystem links below rely on its SOURCE INDEX references or README workflow, not inspection of every implementation.

Main entry points: [`src/main/java/com/autoheal/AutoHealLocator.java`](https://github.com/headout/autoheal/blob/main/src/main/java/com/autoheal/AutoHealLocator.java) (AutoHeal API), [`src/main/java/com/autoheal/core/SelectorCache.java`](https://github.com/headout/autoheal/blob/main/src/main/java/com/autoheal/core/SelectorCache.java) (Selector cache), [`src/main/java/com/autoheal/impl/adapter`](https://github.com/headout/autoheal/tree/main/src/main/java/com/autoheal/impl/adapter) (Framework adapters), [`src/main/java/com/autoheal/impl/locator/CostOptimizedHybridElementLocator.java`](https://github.com/headout/autoheal/blob/main/src/main/java/com/autoheal/impl/locator/CostOptimizedHybridElementLocator.java) (Strategy coordinator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_api["AutoHeal API"]
end

subgraph group_frameworks["Browser Frameworks"]
  node_adapters["Framework adapters"]
  node_selenium["Selenium adapter"]
  node_playwright["Playwright adapter"]
  node_browser["Browser automation"]
  node_parser["Playwright parser"]
end

subgraph group_healing["Locator Healing"]
  node_hybrid["Strategy coordinator"]
  node_dom["DOM healing"]
  node_visual["Visual healing"]
  node_ai["AI service"]
  node_cache["Selector cache<br/>[SelectorCache.java]"]
  node_caffeine[("Caffeine cache")]
  node_redis[("Redis cache")]
  node_filecache[("File cache")]
end

subgraph group_support["Runtime Support"]
  node_configuration["Configuration"]
  node_reporting["Healing reports"]
  node_monitoring["Metrics monitoring"]
end

node_test(("Automation test"))
node_ai_provider["AI providers"]

node_test -->|"calls"| node_api
node_api -->|"uses"| node_adapters
node_api -->|"dispatches"| node_hybrid
node_api -->|"checks cache"| node_cache
node_api -->|"configures"| node_configuration
node_api -.->|"reports through"| node_reporting
node_api -.->|"monitors through"| node_monitoring
node_adapters -->|"includes"| node_selenium
node_adapters -->|"includes"| node_playwright
node_selenium -->|"adapts"| node_browser
node_playwright -->|"adapts"| node_browser
node_api -->|"parses locators"| node_parser
node_parser -->|"produces locator model"| node_playwright
node_hybrid -->|"tries strategy"| node_dom
node_hybrid -->|"tries strategy"| node_visual
node_visual -->|"requests analysis"| node_ai
node_ai -->|"calls providers"| node_ai_provider
node_cache -.->|"implemented by"| node_caffeine
node_cache -.->|"implemented by"| node_redis
node_cache -->|"implemented by"| node_filecache

click node_api "https://github.com/headout/autoheal/blob/main/src/main/java/com/autoheal/AutoHealLocator.java"
click node_adapters "https://github.com/headout/autoheal/tree/main/src/main/java/com/autoheal/impl/adapter"
click node_selenium "https://github.com/headout/autoheal/blob/main/src/main/java/com/autoheal/impl/adapter/SeleniumWebAutomationAdapter.java"
click node_playwright "https://github.com/headout/autoheal/blob/main/src/main/java/com/autoheal/impl/adapter/PlaywrightWebAutomationAdapter.java"
click node_parser "https://github.com/headout/autoheal/blob/main/src/main/java/com/autoheal/util/PlaywrightLocatorParser.java"
click node_hybrid "https://github.com/headout/autoheal/blob/main/src/main/java/com/autoheal/impl/locator/CostOptimizedHybridElementLocator.java"
click node_dom "https://github.com/headout/autoheal/blob/main/src/main/java/com/autoheal/impl/locator/DOMElementLocator.java"
click node_visual "https://github.com/headout/autoheal/blob/main/src/main/java/com/autoheal/impl/locator/VisualElementLocator.java"
click node_ai "https://github.com/headout/autoheal/blob/main/src/main/java/com/autoheal/impl/ai/ResilientAIService.java"
click node_cache "https://github.com/headout/autoheal/blob/main/src/main/java/com/autoheal/core/SelectorCache.java"
click node_caffeine "https://github.com/headout/autoheal/blob/main/src/main/java/com/autoheal/impl/cache/CaffeineBasedSelectorCache.java"
click node_redis "https://github.com/headout/autoheal/blob/main/src/main/java/com/autoheal/impl/cache/RedisBasedSelectorCache.java"
click node_filecache "https://github.com/headout/autoheal/blob/main/src/main/java/com/autoheal/impl/cache/PersistentFileSelectorCache.java"
click node_configuration "https://github.com/headout/autoheal/tree/main/src/main/java/com/autoheal/config"
click node_reporting "https://github.com/headout/autoheal/blob/main/src/main/java/com/autoheal/reporting/AutoHealReporter.java"
click node_monitoring "https://github.com/headout/autoheal/blob/main/src/main/java/com/autoheal/monitoring/AutoHealMonitor.java"

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_api toneBlue
class node_adapters,node_selenium,node_playwright,node_browser,node_parser toneAmber
class node_hybrid,node_dom,node_visual,node_ai,node_cache,node_caffeine,node_redis,node_filecache toneMint
class node_configuration,node_reporting,node_monitoring toneRose
class node_test,node_ai_provider toneIndigo
```

## Components

### Public API

- [AutoHeal API](https://github.com/headout/autoheal/blob/main/src/main/java/com/autoheal/AutoHealLocator.java): `src/main/java/com/autoheal/AutoHealLocator.java`

### Browser Frameworks

- [Framework adapters](https://github.com/headout/autoheal/tree/main/src/main/java/com/autoheal/impl/adapter): `src/main/java/com/autoheal/impl/adapter`
- [Selenium adapter](https://github.com/headout/autoheal/blob/main/src/main/java/com/autoheal/impl/adapter/SeleniumWebAutomationAdapter.java): `src/main/java/com/autoheal/impl/adapter/SeleniumWebAutomationAdapter.java`
- [Playwright adapter](https://github.com/headout/autoheal/blob/main/src/main/java/com/autoheal/impl/adapter/PlaywrightWebAutomationAdapter.java): `src/main/java/com/autoheal/impl/adapter/PlaywrightWebAutomationAdapter.java`
- **Browser automation**
- [Playwright parser](https://github.com/headout/autoheal/blob/main/src/main/java/com/autoheal/util/PlaywrightLocatorParser.java): `src/main/java/com/autoheal/util/PlaywrightLocatorParser.java`

### Locator Healing

- [Strategy coordinator](https://github.com/headout/autoheal/blob/main/src/main/java/com/autoheal/impl/locator/CostOptimizedHybridElementLocator.java): `src/main/java/com/autoheal/impl/locator/CostOptimizedHybridElementLocator.java`
- [DOM healing](https://github.com/headout/autoheal/blob/main/src/main/java/com/autoheal/impl/locator/DOMElementLocator.java): `src/main/java/com/autoheal/impl/locator/DOMElementLocator.java`
- [Visual healing](https://github.com/headout/autoheal/blob/main/src/main/java/com/autoheal/impl/locator/VisualElementLocator.java): `src/main/java/com/autoheal/impl/locator/VisualElementLocator.java`
- [AI service](https://github.com/headout/autoheal/blob/main/src/main/java/com/autoheal/impl/ai/ResilientAIService.java): `src/main/java/com/autoheal/impl/ai/ResilientAIService.java`
- [Selector cache](https://github.com/headout/autoheal/blob/main/src/main/java/com/autoheal/core/SelectorCache.java): `src/main/java/com/autoheal/core/SelectorCache.java`
- [Caffeine cache](https://github.com/headout/autoheal/blob/main/src/main/java/com/autoheal/impl/cache/CaffeineBasedSelectorCache.java): `src/main/java/com/autoheal/impl/cache/CaffeineBasedSelectorCache.java`
- [Redis cache](https://github.com/headout/autoheal/blob/main/src/main/java/com/autoheal/impl/cache/RedisBasedSelectorCache.java): `src/main/java/com/autoheal/impl/cache/RedisBasedSelectorCache.java`
- [File cache](https://github.com/headout/autoheal/blob/main/src/main/java/com/autoheal/impl/cache/PersistentFileSelectorCache.java): `src/main/java/com/autoheal/impl/cache/PersistentFileSelectorCache.java`

### Runtime Support

- [Configuration](https://github.com/headout/autoheal/tree/main/src/main/java/com/autoheal/config): `src/main/java/com/autoheal/config`
- [Healing reports](https://github.com/headout/autoheal/blob/main/src/main/java/com/autoheal/reporting/AutoHealReporter.java): `src/main/java/com/autoheal/reporting/AutoHealReporter.java`
- [Metrics monitoring](https://github.com/headout/autoheal/blob/main/src/main/java/com/autoheal/monitoring/AutoHealMonitor.java): `src/main/java/com/autoheal/monitoring/AutoHealMonitor.java`

### Other components

- **Automation test**
- **AI providers**

## Connections

- Automation test → AutoHeal API: calls (evidence: `README.md`)
- AutoHeal API → Framework adapters: uses (evidence: `src/main/java/com/autoheal/AutoHealLocator.java`)
- AutoHeal API → Strategy coordinator: dispatches (evidence: `src/main/java/com/autoheal/AutoHealLocator.java`)
- AutoHeal API → Selector cache: checks cache (evidence: `README.md`)
- AutoHeal API → Configuration: configures (evidence: `src/main/java/com/autoheal/AutoHealLocator.java`)
- AutoHeal API → Healing reports: reports through (evidence: `src/main/java/com/autoheal/AutoHealLocator.java`)
- AutoHeal API → Metrics monitoring: monitors through
- Framework adapters → Selenium adapter: includes (evidence: `README.md`)
- Framework adapters → Playwright adapter: includes (evidence: `README.md`)
- Selenium adapter → Browser automation: adapts (evidence: `README.md`)
- Playwright adapter → Browser automation: adapts (evidence: `README.md`)
- AutoHeal API → Playwright parser: parses locators (evidence: `src/main/java/com/autoheal/AutoHealLocator.java`)
- Playwright parser → Playwright adapter: produces locator model (evidence: `src/main/java/com/autoheal/util/PlaywrightLocatorParser.java`)
- Strategy coordinator → DOM healing: tries strategy (evidence: `src/main/java/com/autoheal/impl/locator/CostOptimizedHybridElementLocator.java`)
- Strategy coordinator → Visual healing: tries strategy (evidence: `src/main/java/com/autoheal/impl/locator/CostOptimizedHybridElementLocator.java`)
- Visual healing → AI service: requests analysis (evidence: `src/main/java/com/autoheal/impl/locator/VisualElementLocator.java`)
- AI service → AI providers: calls providers (evidence: `src/main/java/com/autoheal/impl/ai/ResilientAIService.java`)
- Selector cache → Caffeine cache: implemented by
- Selector cache → Redis cache: implemented by
- Selector cache → File cache: implemented by (evidence: `src/main/java/com/autoheal/impl/cache/PersistentFileSelectorCache.java`)
