# ctrondlp/pyguitest-recorder architecture

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

- Interactive diagram: https://gitdiagram.com/ctrondlp/pyguitest-recorder
- Repository: https://github.com/ctrondlp/pyguitest-recorder

## Overview

pyguitest-recorder captures desktop input, resolves interactions to accessible GUI targets where possible, converts observations into canonical events, and generates standalone pyguitest scripts. Users can also save recordings and regenerate scripts later. The graph reflects README capabilities and indexed source references; several implementation details are unsampled, so only documented or indexed relationships are connected.

Main entry points: [`src/pyguitest_recorder/recorder.py`](https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/recorder.py) (Recording lifecycle), [`src/pyguitest_recorder/cli.py`](https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/cli.py) (CLI modes), [`src/pyguitest_recorder/backends/x11.py`](https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/backends/x11.py) (X11 capture), [`src/pyguitest_recorder/backends/win32.py`](https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/backends/win32.py) (Windows capture)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Command and settings"]
  node_cli["CLI modes<br/>[cli.py]"]
  node_settings["Settings<br/>[settings.py]"]
  node_platforms["Platform detection<br/>[platforms.py]"]
end

subgraph group_capture["Input capture"]
  node_recorder["Recording lifecycle<br/>[recorder.py]"]
  node_x11["X11 capture<br/>[x11.py]"]
  node_win["Windows capture<br/>[win32.py]"]
  node_mac["macOS capture<br/>[macos.py]"]
  node_raw["Raw event interface<br/>[base.py]"]
  node_stopkey["Stop-key recognition<br/>[stopkey.py]"]
end

subgraph group_interpret["Event interpretation"]
  node_resolver["Window and element resolver<br/>[resolver.py]"]
  node_normalizer["Event normalization<br/>[normalize.py]"]
  node_sync["Wait inference<br/>[sync.py]"]
end

subgraph group_output["Recording and generation"]
  node_events["Canonical events<br/>[events.py]"]
  node_recording["Recording model<br/>[recording.py]"]
  node_generator["Python generator<br/>[python.py]"]
  node_script["Generated test script"]
end

node_user(("Recorder user"))
node_desktop(("Desktop activity"))
node_pyguitest["pyguitest runtime"]

node_user -->|"starts or configures"| node_cli
node_cli -->|"loads settings"| node_settings
node_cli -->|"checks platform"| node_platforms
node_cli -->|"starts recording"| node_recorder
node_desktop -->|"provides input"| node_x11
node_desktop -->|"provides input"| node_win
node_desktop -->|"provides input"| node_mac
node_recorder -->|"selects capture backend"| node_x11
node_recorder -->|"selects capture backend"| node_win
node_recorder -->|"selects capture backend"| node_mac
node_x11 -->|"produces raw events"| node_raw
node_win -->|"produces raw events"| node_raw
node_mac -->|"produces raw events"| node_raw
node_recorder -->|"recognizes stop chord"| node_stopkey
node_recorder -->|"resolves context"| node_resolver
node_resolver -->|"queries GUI session"| node_pyguitest
node_recorder -->|"normalizes captured events"| node_normalizer
node_normalizer -->|"creates canonical events"| node_events
node_recorder -->|"adds normalized events"| node_recording
node_events -->|"stored as recording events"| node_recording
node_cli -->|"infers waits for generation"| node_sync
node_cli -->|"generates or regenerates"| node_generator
node_generator -->|"renders Python source"| node_script
node_script -->|"replays GUI test"| node_pyguitest
node_user -->|"runs generated test"| node_script

click node_cli "https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/cli.py"
click node_settings "https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/config/settings.py"
click node_platforms "https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/platforms.py"
click node_recorder "https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/recorder.py"
click node_x11 "https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/backends/x11.py"
click node_win "https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/backends/win32.py"
click node_mac "https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/backends/macos.py"
click node_raw "https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/backends/base.py"
click node_stopkey "https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/stopkey.py"
click node_resolver "https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/windows/resolver.py"
click node_normalizer "https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/analyzer/normalize.py"
click node_sync "https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/analyzer/sync.py"
click node_events "https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/model/events.py"
click node_recording "https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/model/recording.py"
click node_generator "https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/generator/python.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_cli,node_settings,node_platforms,node_user toneBlue
class node_recorder,node_x11,node_win,node_mac,node_raw,node_stopkey toneAmber
class node_resolver,node_normalizer,node_sync toneMint
class node_events,node_recording,node_generator,node_script toneRose
class node_desktop,node_pyguitest toneIndigo
```

## Components

### Command and settings

- [CLI modes](https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/cli.py): `src/pyguitest_recorder/cli.py`
- [Settings](https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/config/settings.py): `src/pyguitest_recorder/config/settings.py`
- [Platform detection](https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/platforms.py): `src/pyguitest_recorder/platforms.py`

### Input capture

- [Recording lifecycle](https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/recorder.py): `src/pyguitest_recorder/recorder.py`
- [X11 capture](https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/backends/x11.py): `src/pyguitest_recorder/backends/x11.py`
- [Windows capture](https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/backends/win32.py): `src/pyguitest_recorder/backends/win32.py`
- [macOS capture](https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/backends/macos.py): `src/pyguitest_recorder/backends/macos.py`
- [Raw event interface](https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/backends/base.py): `src/pyguitest_recorder/backends/base.py`
- [Stop-key recognition](https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/stopkey.py): `src/pyguitest_recorder/stopkey.py`

### Event interpretation

- [Window and element resolver](https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/windows/resolver.py): `src/pyguitest_recorder/windows/resolver.py`
- [Event normalization](https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/analyzer/normalize.py): `src/pyguitest_recorder/analyzer/normalize.py`
- [Wait inference](https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/analyzer/sync.py): `src/pyguitest_recorder/analyzer/sync.py`

### Recording and generation

- [Canonical events](https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/model/events.py): `src/pyguitest_recorder/model/events.py`
- [Recording model](https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/model/recording.py): `src/pyguitest_recorder/model/recording.py`
- [Python generator](https://github.com/ctrondlp/pyguitest-recorder/blob/main/src/pyguitest_recorder/generator/python.py): `src/pyguitest_recorder/generator/python.py`
- **Generated test script**

### Other components

- **Recorder user**
- **Desktop activity**
- **pyguitest runtime**

## Connections

- Recorder user → CLI modes: starts or configures (evidence: `README.md`)
- CLI modes → Settings: loads settings (evidence: `src/pyguitest_recorder/cli.py`)
- CLI modes → Platform detection: checks platform (evidence: `src/pyguitest_recorder/cli.py`)
- CLI modes → Recording lifecycle: starts recording (evidence: `src/pyguitest_recorder/cli.py`)
- Desktop activity → X11 capture: provides input (evidence: `README.md`)
- Desktop activity → Windows capture: provides input (evidence: `README.md`)
- Desktop activity → macOS capture: provides input (evidence: `README.md`)
- Recording lifecycle → X11 capture: selects capture backend (evidence: `src/pyguitest_recorder/recorder.py`)
- Recording lifecycle → Windows capture: selects capture backend (evidence: `src/pyguitest_recorder/recorder.py`)
- Recording lifecycle → macOS capture: selects capture backend (evidence: `src/pyguitest_recorder/recorder.py`)
- X11 capture → Raw event interface: produces raw events (evidence: `src/pyguitest_recorder/backends/x11.py`)
- Windows capture → Raw event interface: produces raw events (evidence: `src/pyguitest_recorder/backends/win32.py`)
- macOS capture → Raw event interface: produces raw events (evidence: `src/pyguitest_recorder/backends/macos.py`)
- Recording lifecycle → Stop-key recognition: recognizes stop chord (evidence: `src/pyguitest_recorder/recorder.py`)
- Recording lifecycle → Window and element resolver: resolves context (evidence: `src/pyguitest_recorder/recorder.py`)
- Window and element resolver → pyguitest runtime: queries GUI session (evidence: `src/pyguitest_recorder/windows/resolver.py`)
- Recording lifecycle → Event normalization: normalizes captured events (evidence: `src/pyguitest_recorder/recorder.py`)
- Event normalization → Canonical events: creates canonical events (evidence: `src/pyguitest_recorder/analyzer/normalize.py`)
- Recording lifecycle → Recording model: adds normalized events
- Canonical events → Recording model: stored as recording events (evidence: `src/pyguitest_recorder/model/recording.py`)
- CLI modes → Wait inference: infers waits for generation (evidence: `src/pyguitest_recorder/cli.py`)
- CLI modes → Python generator: generates or regenerates (evidence: `src/pyguitest_recorder/cli.py`)
- Python generator → Generated test script: renders Python source (evidence: `README.md`)
- Generated test script → pyguitest runtime: replays GUI test (evidence: `README.md`)
- Recorder user → Generated test script: runs generated test (evidence: `README.md`)
