# adirwt852-cloud/crash-test-guard architecture

> Architecture diagram of the GitHub repository adirwt852-cloud/crash-test-guard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adirwt852-cloud/crash-test-guard
- Repository: https://github.com/adirwt852-cloud/crash-test-guard

## Overview

Crash-Test Guard is a CI reliability gate for stateful agents: load a test configuration, run a baseline and crash scenario, restart and resume the agent, verify recovery, then emit a report and pass/fail status. The CLI wires configuration, execution, orchestration, and reporting; the engine owns crash timing and verification, while executors manage local processes or Docker containers and the protocol client talks to the agent. The README documents JUnit and human reports and the six-endpoint agent protocol. Some scenario details are unsampled, so links beyond the shown calls are limited to documented relationships.

Main entry points: [`internal/orchestrator/engine.go`](https://github.com/adirwt852-cloud/crash-test-guard/blob/main/internal/orchestrator/engine.go) (Test Orchestrator), [`cmd/crash-test-guard/main.go`](https://github.com/adirwt852-cloud/crash-test-guard/blob/main/cmd/crash-test-guard/main.go) (Test CLI), [`internal/executor/executor.go`](https://github.com/adirwt852-cloud/crash-test-guard/blob/main/internal/executor/executor.go) (Executor Interface), [`internal/protocol/client.go`](https://github.com/adirwt852-cloud/crash-test-guard/blob/main/internal/protocol/client.go) (HTTP Protocol Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and Configuration"]
  node_cli["Test CLI<br/>[main.go]"]
  node_config["Test Configuration<br/>[config.go]"]
end

subgraph group_testflow["Crash Test Workflow"]
  node_engine["Test Orchestrator<br/>[engine.go]"]
  node_baseline["Baseline Run<br/>[engine.go]"]
  node_crash["Crash Scenario<br/>[engine.go]"]
  node_recovery["Resume and Verify<br/>[engine.go]"]
end

subgraph group_agent["Agent Integration"]
  node_executor["Executor Interface<br/>[executor.go]"]
  node_local["Local Process<br/>[local.go]"]
  node_docker["Docker Container<br/>[docker.go]"]
  node_protocol["HTTP Protocol Client<br/>[client.go]"]
end

subgraph group_report["Reporting"]
  node_human["Human Report<br/>[human.go]"]
  node_junit["JUnit Report<br/>[junit.go]"]
  node_json["JSON Report<br/>[main.go]"]
end

node_user(("CI or Engineer"))
node_agentservice["Agent Under Test"]

node_user -->|"runs test"| node_cli
node_cli -->|"loads config"| node_config
node_cli -->|"runs test"| node_engine
node_cli -->|"selects report"| node_human
node_cli -->|"selects report"| node_junit
node_cli -->|"writes report"| node_json
node_engine -->|"runs baseline"| node_baseline
node_engine -->|"injects crash"| node_crash
node_engine -->|"verifies recovery"| node_recovery
node_engine -->|"starts agent"| node_executor
node_engine -->|"crashes and restarts"| node_executor
node_engine -->|"controls workflow"| node_protocol
node_local -->|"implements lifecycle"| node_executor
node_docker -->|"implements lifecycle"| node_executor
node_protocol -->|"calls HTTP endpoints"| node_agentservice
node_engine -->|"reports results"| node_human
node_engine -->|"reports results"| node_junit

click node_cli "https://github.com/adirwt852-cloud/crash-test-guard/blob/main/cmd/crash-test-guard/main.go"
click node_config "https://github.com/adirwt852-cloud/crash-test-guard/blob/main/internal/config/config.go"
click node_engine "https://github.com/adirwt852-cloud/crash-test-guard/blob/main/internal/orchestrator/engine.go"
click node_baseline "https://github.com/adirwt852-cloud/crash-test-guard/blob/main/internal/orchestrator/engine.go"
click node_crash "https://github.com/adirwt852-cloud/crash-test-guard/blob/main/internal/orchestrator/engine.go"
click node_recovery "https://github.com/adirwt852-cloud/crash-test-guard/blob/main/internal/orchestrator/engine.go"
click node_executor "https://github.com/adirwt852-cloud/crash-test-guard/blob/main/internal/executor/executor.go"
click node_local "https://github.com/adirwt852-cloud/crash-test-guard/blob/main/internal/executor/local.go"
click node_docker "https://github.com/adirwt852-cloud/crash-test-guard/blob/main/internal/executor/docker.go"
click node_protocol "https://github.com/adirwt852-cloud/crash-test-guard/blob/main/internal/protocol/client.go"
click node_human "https://github.com/adirwt852-cloud/crash-test-guard/blob/main/internal/reporter/human.go"
click node_junit "https://github.com/adirwt852-cloud/crash-test-guard/blob/main/internal/reporter/junit.go"
click node_json "https://github.com/adirwt852-cloud/crash-test-guard/blob/main/cmd/crash-test-guard/main.go"

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_config toneBlue
class node_engine,node_baseline,node_crash,node_recovery toneAmber
class node_executor,node_local,node_docker,node_protocol toneMint
class node_human,node_junit,node_json toneRose
class node_user,node_agentservice toneIndigo
```

## Components

### CLI and Configuration

- [Test CLI](https://github.com/adirwt852-cloud/crash-test-guard/blob/main/cmd/crash-test-guard/main.go): `cmd/crash-test-guard/main.go`
- [Test Configuration](https://github.com/adirwt852-cloud/crash-test-guard/blob/main/internal/config/config.go): `internal/config/config.go`

### Crash Test Workflow

- [Test Orchestrator](https://github.com/adirwt852-cloud/crash-test-guard/blob/main/internal/orchestrator/engine.go): `internal/orchestrator/engine.go`
- [Baseline Run](https://github.com/adirwt852-cloud/crash-test-guard/blob/main/internal/orchestrator/engine.go): `internal/orchestrator/engine.go`
- [Crash Scenario](https://github.com/adirwt852-cloud/crash-test-guard/blob/main/internal/orchestrator/engine.go): `internal/orchestrator/engine.go`
- [Resume and Verify](https://github.com/adirwt852-cloud/crash-test-guard/blob/main/internal/orchestrator/engine.go): `internal/orchestrator/engine.go`

### Agent Integration

- [Executor Interface](https://github.com/adirwt852-cloud/crash-test-guard/blob/main/internal/executor/executor.go): `internal/executor/executor.go`
- [Local Process](https://github.com/adirwt852-cloud/crash-test-guard/blob/main/internal/executor/local.go): `internal/executor/local.go`
- [Docker Container](https://github.com/adirwt852-cloud/crash-test-guard/blob/main/internal/executor/docker.go): `internal/executor/docker.go`
- [HTTP Protocol Client](https://github.com/adirwt852-cloud/crash-test-guard/blob/main/internal/protocol/client.go): `internal/protocol/client.go`

### Reporting

- [Human Report](https://github.com/adirwt852-cloud/crash-test-guard/blob/main/internal/reporter/human.go): `internal/reporter/human.go`
- [JUnit Report](https://github.com/adirwt852-cloud/crash-test-guard/blob/main/internal/reporter/junit.go): `internal/reporter/junit.go`
- [JSON Report](https://github.com/adirwt852-cloud/crash-test-guard/blob/main/cmd/crash-test-guard/main.go): `cmd/crash-test-guard/main.go`

### Other components

- **CI or Engineer**
- **Agent Under Test**

## Connections

- CI or Engineer → Test CLI: runs test (evidence: `README.md`)
- Test CLI → Test Configuration: loads config (evidence: `cmd/crash-test-guard/main.go`)
- Test CLI → Test Orchestrator: runs test (evidence: `cmd/crash-test-guard/main.go`)
- Test CLI → Human Report: selects report (evidence: `cmd/crash-test-guard/main.go`)
- Test CLI → JUnit Report: selects report (evidence: `cmd/crash-test-guard/main.go`)
- Test CLI → JSON Report: writes report (evidence: `cmd/crash-test-guard/main.go`)
- Test Orchestrator → Baseline Run: runs baseline (evidence: `internal/orchestrator/engine.go`)
- Test Orchestrator → Crash Scenario: injects crash (evidence: `internal/orchestrator/engine.go`)
- Test Orchestrator → Resume and Verify: verifies recovery (evidence: `internal/orchestrator/engine.go`)
- Test Orchestrator → Executor Interface: starts agent (evidence: `internal/orchestrator/engine.go`)
- Test Orchestrator → Executor Interface: crashes and restarts (evidence: `internal/orchestrator/engine.go`)
- Test Orchestrator → HTTP Protocol Client: controls workflow (evidence: `internal/orchestrator/engine.go`)
- Local Process → Executor Interface: implements lifecycle (evidence: `internal/executor/local.go`)
- Docker Container → Executor Interface: implements lifecycle (evidence: `internal/executor/docker.go`)
- HTTP Protocol Client → Agent Under Test: calls HTTP endpoints (evidence: `README.md`)
- Test Orchestrator → Human Report: reports results
- Test Orchestrator → JUnit Report: reports results
