Architecture
These pages show how Behat Steps works inside. Read them when you write a trait, extend the library or want to know why a step behaves the way it does. Writing scenarios needs none of them. The section holds the following pages:
- Logical architecture shows the parts and which way they depend on each other.
- 3 pages cover 1 layer each:
- Backend layer: the layer that reaches the site and picks a backend for every step by capability.
- Extension layer: the layer that plugs the library into Behat and Mink and gives traits their options.
- Steps layer: the layer that holds every step and helper.
- Data flow shows what runs when, and whose code it is.
- Anatomy of a trait takes a trait apart, line by line.
- Public API and versioning lists what semantic versioning covers, and the exceptions a failing step throws.
- Class inheritance shows what extends what.
An AI agent maintains these pages and their diagrams through the update-architecture-docs skill in .claude/skills/update-architecture-docs/SKILL.md. The agent draws the diagrams with the drawio-skill. Everything here is traced from the source code, and where the pages and the code disagree, the code wins.
To look something up, use the references:
- Web steps and Drupal steps list the steps.
- HELPERS.md lists the helpers behind them.
- Configuration reference lists the options and tags.
Diagram sources
Each diagram has a draw.io source and 2 exported SVGs, 1 for the light color mode and 1 for the dark. The diagram's page embeds both, and the site shows the SVG that matches the color mode. All 3 files are committed, so a reviewer sees the source diff and the rendered result. The following table lists every diagram of this section:
| Diagram | Page | Source | Renders |
|---|---|---|---|
| Logical architecture | Logical architecture | logical-architecture.drawio | light, dark |
| Backend selection | Backend layer | backend-selection.drawio | light, dark |
| Extension layer | Extension layer | extension-layer.drawio | light, dark |
| Steps layer | Steps layer | steps-layer.drawio | light, dark |
| Data flow | Data flow | data-flow.drawio | light, dark |
| Class inheritance | Class inheritance | class-inheritance.drawio | light, dark |
The 3 diagrams of the HTTP clients guide sit beside the guide in docs/content/guides/, drawn and checked the same way.
To change a diagram by hand:
-
Open its source in draw.io, edit it and save it.
-
From the repository root, export every SVG again:
php scripts/draw-diagram.php --export \docs/content/architecture docs/content/guides
Each SVG records the hash of the source it came from. php scripts/draw-diagram.php --check docs/content/architecture docs/content/guides exits with an error when an SVG was exported from an older source or a diagram lacks either of its SVGs. The unit suite runs the same check.
After a structural change, ask the AI agent to "update architecture docs". Structural changes include a new layer, namespace, backend or capability. A change to an inheritance tree or the scenario lifecycle counts too. The agent re-traces the affected diagrams and pages from the current code and redraws them through the update-architecture-docs skill.