# vbforge/deadlock-visualizer architecture

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

- Interactive diagram: https://gitdiagram.com/vbforge/deadlock-visualizer
- Repository: https://github.com/vbforge/deadlock-visualizer

## Overview

Deadlock Visualizer is an interactive teaching application: a browser starts or clears a real ABBA deadlock scenario, polls its status, and displays thread/lock details and a live dependency graph. The backend owns scenario lifecycle and lock allocation, while a JVM probe supplies thread and deadlock observations used in the JSON snapshot. README documents diagnostic and Actuator endpoints as additional capabilities. Source excerpts support the central calls; template wiring and Actuator implementation details are documented but not excerpted.

Main entry points: [`src/main/java/com/vbforge/deadlock/engine/DeadlockEngine.java`](https://github.com/vbforge/deadlock-visualizer/blob/main/src/main/java/com/vbforge/deadlock/engine/DeadlockEngine.java) (Scenario lifecycle), [`src/main/resources/templates/index.html`](https://github.com/vbforge/deadlock-visualizer/blob/main/src/main/resources/templates/index.html) (Visualizer page), [`src/main/java/com/vbforge/deadlock/web/DeadlockController.java`](https://github.com/vbforge/deadlock-visualizer/blob/main/src/main/java/com/vbforge/deadlock/web/DeadlockController.java) (Deadlock REST API), [`src/main/java/com/vbforge/deadlock/engine/ThreadMxBeanProbe.java`](https://github.com/vbforge/deadlock-visualizer/blob/main/src/main/java/com/vbforge/deadlock/engine/ThreadMxBeanProbe.java) (Thread MXBean probe)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Browser presentation"]
  node_template["Visualizer page<br/>[index.html]"]
  node_controls["Polling and controls<br/>[deadlock.js]"]
  node_graph["Lock graph renderer<br/>[lockGraph.js]"]
  node_styles["Page styling<br/>[app.css]"]
end

subgraph group_web["Web interface"]
  node_home["Home page handler"]
  node_api["Deadlock REST API"]
end

subgraph group_scenario["Scenario engine"]
  node_engine["Scenario lifecycle"]
  node_locks["Scenario lock pair<br/>[LockRegistry.java]"]
  node_status["Scenario status"]
end

subgraph group_inspection["JVM inspection and contract"]
  node_probe["Thread MXBean probe"]
  node_snapshot["Status snapshot"]
  node_thread["Thread details"]
end

node_browser(("User browser"))
node_jvm["JVM thread management"]
node_actuator["Actuator endpoints"]

node_browser -->|"opens page"| node_template
node_home -->|"renders"| node_template
node_template -->|"loads script"| node_controls
node_template -->|"loads script"| node_graph
node_template -->|"loads styles"| node_styles
node_browser -->|"uses controls"| node_controls
node_controls -->|"requests status"| node_api
node_controls -->|"delegates render"| node_graph
node_api -->|"invokes lifecycle"| node_engine
node_api -->|"reads lock names"| node_locks
node_engine -->|"rotates and reads"| node_locks
node_engine -->|"queries threads"| node_probe
node_engine -->|"updates state"| node_status
node_engine -->|"builds snapshot"| node_snapshot
node_probe -->|"inspects threads"| node_jvm
node_probe -->|"names monitors"| node_locks
node_probe -->|"builds details"| node_thread
node_snapshot -->|"includes status"| node_status
node_snapshot -->|"contains details"| node_thread
node_api -->|"diagnoses threads"| node_jvm
node_browser -.->|"requests diagnostics"| node_actuator

click node_home "https://github.com/vbforge/deadlock-visualizer/blob/main/src/main/java/com/vbforge/deadlock/web/HomeController.java"
click node_template "https://github.com/vbforge/deadlock-visualizer/blob/main/src/main/resources/templates/index.html"
click node_controls "https://github.com/vbforge/deadlock-visualizer/blob/main/src/main/resources/static/js/deadlock.js"
click node_graph "https://github.com/vbforge/deadlock-visualizer/blob/main/src/main/resources/static/js/lockGraph.js"
click node_styles "https://github.com/vbforge/deadlock-visualizer/blob/main/src/main/resources/static/css/app.css"
click node_api "https://github.com/vbforge/deadlock-visualizer/blob/main/src/main/java/com/vbforge/deadlock/web/DeadlockController.java"
click node_engine "https://github.com/vbforge/deadlock-visualizer/blob/main/src/main/java/com/vbforge/deadlock/engine/DeadlockEngine.java"
click node_locks "https://github.com/vbforge/deadlock-visualizer/blob/main/src/main/java/com/vbforge/deadlock/engine/LockRegistry.java"
click node_status "https://github.com/vbforge/deadlock-visualizer/blob/main/src/main/java/com/vbforge/deadlock/engine/DeadlockStatus.java"
click node_probe "https://github.com/vbforge/deadlock-visualizer/blob/main/src/main/java/com/vbforge/deadlock/engine/ThreadMxBeanProbe.java"
click node_snapshot "https://github.com/vbforge/deadlock-visualizer/blob/main/src/main/java/com/vbforge/deadlock/engine/dto/DeadlockSnapshot.java"
click node_thread "https://github.com/vbforge/deadlock-visualizer/blob/main/src/main/java/com/vbforge/deadlock/engine/dto/ThreadSnapshot.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_template,node_controls,node_graph,node_styles,node_browser toneBlue
class node_home,node_api toneAmber
class node_engine,node_locks,node_status toneMint
class node_probe,node_snapshot,node_thread toneRose
class node_jvm,node_actuator toneIndigo
```

## Components

### Browser presentation

- [Visualizer page](https://github.com/vbforge/deadlock-visualizer/blob/main/src/main/resources/templates/index.html): `src/main/resources/templates/index.html`
- [Polling and controls](https://github.com/vbforge/deadlock-visualizer/blob/main/src/main/resources/static/js/deadlock.js): `src/main/resources/static/js/deadlock.js`
- [Lock graph renderer](https://github.com/vbforge/deadlock-visualizer/blob/main/src/main/resources/static/js/lockGraph.js): `src/main/resources/static/js/lockGraph.js`
- [Page styling](https://github.com/vbforge/deadlock-visualizer/blob/main/src/main/resources/static/css/app.css): `src/main/resources/static/css/app.css`

### Web interface

- [Home page handler](https://github.com/vbforge/deadlock-visualizer/blob/main/src/main/java/com/vbforge/deadlock/web/HomeController.java): `src/main/java/com/vbforge/deadlock/web/HomeController.java`
- [Deadlock REST API](https://github.com/vbforge/deadlock-visualizer/blob/main/src/main/java/com/vbforge/deadlock/web/DeadlockController.java): `src/main/java/com/vbforge/deadlock/web/DeadlockController.java`

### Scenario engine

- [Scenario lifecycle](https://github.com/vbforge/deadlock-visualizer/blob/main/src/main/java/com/vbforge/deadlock/engine/DeadlockEngine.java): `src/main/java/com/vbforge/deadlock/engine/DeadlockEngine.java`
- [Scenario lock pair](https://github.com/vbforge/deadlock-visualizer/blob/main/src/main/java/com/vbforge/deadlock/engine/LockRegistry.java): `src/main/java/com/vbforge/deadlock/engine/LockRegistry.java`
- [Scenario status](https://github.com/vbforge/deadlock-visualizer/blob/main/src/main/java/com/vbforge/deadlock/engine/DeadlockStatus.java): `src/main/java/com/vbforge/deadlock/engine/DeadlockStatus.java`

### JVM inspection and contract

- [Thread MXBean probe](https://github.com/vbforge/deadlock-visualizer/blob/main/src/main/java/com/vbforge/deadlock/engine/ThreadMxBeanProbe.java): `src/main/java/com/vbforge/deadlock/engine/ThreadMxBeanProbe.java`
- [Status snapshot](https://github.com/vbforge/deadlock-visualizer/blob/main/src/main/java/com/vbforge/deadlock/engine/dto/DeadlockSnapshot.java): `src/main/java/com/vbforge/deadlock/engine/dto/DeadlockSnapshot.java`
- [Thread details](https://github.com/vbforge/deadlock-visualizer/blob/main/src/main/java/com/vbforge/deadlock/engine/dto/ThreadSnapshot.java): `src/main/java/com/vbforge/deadlock/engine/dto/ThreadSnapshot.java`

### Other components

- **User browser**
- **JVM thread management**
- **Actuator endpoints**

## Connections

- User browser → Visualizer page: opens page (evidence: `README.md`)
- Home page handler → Visualizer page: renders (evidence: `README.md`)
- Visualizer page → Polling and controls: loads script (evidence: `README.md`)
- Visualizer page → Lock graph renderer: loads script (evidence: `README.md`)
- Visualizer page → Page styling: loads styles (evidence: `README.md`)
- User browser → Polling and controls: uses controls (evidence: `README.md`)
- Polling and controls → Deadlock REST API: requests status (evidence: `src/main/resources/static/js/deadlock.js`)
- Polling and controls → Lock graph renderer: delegates render (evidence: `README.md`)
- Deadlock REST API → Scenario lifecycle: invokes lifecycle (evidence: `src/main/java/com/vbforge/deadlock/web/DeadlockController.java`)
- Deadlock REST API → Scenario lock pair: reads lock names (evidence: `src/main/java/com/vbforge/deadlock/web/DeadlockController.java`)
- Scenario lifecycle → Scenario lock pair: rotates and reads (evidence: `src/main/java/com/vbforge/deadlock/engine/DeadlockEngine.java`)
- Scenario lifecycle → Thread MXBean probe: queries threads (evidence: `src/main/java/com/vbforge/deadlock/engine/DeadlockEngine.java`)
- Scenario lifecycle → Scenario status: updates state (evidence: `src/main/java/com/vbforge/deadlock/engine/DeadlockEngine.java`)
- Scenario lifecycle → Status snapshot: builds snapshot (evidence: `src/main/java/com/vbforge/deadlock/engine/DeadlockEngine.java`)
- Thread MXBean probe → JVM thread management: inspects threads (evidence: `src/main/java/com/vbforge/deadlock/engine/ThreadMxBeanProbe.java`)
- Thread MXBean probe → Scenario lock pair: names monitors (evidence: `src/main/java/com/vbforge/deadlock/engine/ThreadMxBeanProbe.java`)
- Thread MXBean probe → Thread details: builds details (evidence: `src/main/java/com/vbforge/deadlock/engine/ThreadMxBeanProbe.java`)
- Status snapshot → Scenario status: includes status (evidence: `src/main/java/com/vbforge/deadlock/engine/dto/DeadlockSnapshot.java`)
- Status snapshot → Thread details: contains details (evidence: `src/main/java/com/vbforge/deadlock/engine/dto/DeadlockSnapshot.java`)
- Deadlock REST API → JVM thread management: diagnoses threads (evidence: `src/main/java/com/vbforge/deadlock/web/DeadlockController.java`)
- User browser → Actuator endpoints: requests diagnostics (evidence: `README.md`)
