# yashr-cmd/crash-explainer architecture

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

- Interactive diagram: https://gitdiagram.com/yashr-cmd/crash-explainer
- Repository: https://github.com/yashr-cmd/crash-explainer

## Overview

CrashExplainer is a Minecraft crash-diagnosis mod for Forge and Fabric. Loader adapters invoke the core analyzer, which scans crash reports, rotated logs, and JVM error logs, turns text into reports, and passes them to an explainer. The default heuristic path applies registered rules and produces a diagnosis that the analyzer displays; processed-state storage prevents repeat handling. An optional, user-configured LLM explainer can call an OpenAI-compatible service and fall back to heuristics. Edges reflect README statements and sampled/indexed references; some internal dispatch details are not shown.

Main entry points: [`crashexplainer/core/src/main/java/com/yash/crashexplainer/core/CrashAnalyzer.java`](https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/CrashAnalyzer.java) (Crash analyzer), [`crashexplainer/core/src/main/java/com/yash/crashexplainer/core/LlmExplainer.java`](https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/LlmExplainer.java) (Optional LLM explainer), [`crashexplainer/core/src/main/java/com/yash/crashexplainer/core/DiagnosticEngine.java`](https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/DiagnosticEngine.java) (Rule engine), [`crashexplainer/core/src/main/java/com/yash/crashexplainer/core/rules`](https://github.com/yashr-cmd/crash-explainer/tree/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/rules) (Crash pattern rules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Loader integration"]
  node_fabric["Fabric adapter"]
  node_forge["Forge adapter"]
end

subgraph group_intake["Crash intake"]
  node_analyzer["Crash analyzer<br/>[CrashAnalyzer.java]"]
  node_crashscan["Crash report scan"]
  node_logscan["Rotated log scan"]
  node_hserscan["JVM error scan<br/>[HsErrScanner.java]"]
  node_report["Crash report model<br/>[CrashReport.java]"]
end

subgraph group_diagnosis["Diagnosis"]
  node_config["Explainer config"]
  node_heuristic["Heuristic explainer"]
  node_engine["Rule engine"]
  node_ruleapi["Rule interface<br/>[Rule.java]"]
  node_rules["Crash pattern rules"]
  node_ruleutils["Rule text utilities"]
  node_llm["Optional LLM explainer<br/>[LlmExplainer.java]"]
  node_diagnosisresult["Diagnosis result<br/>[Diagnosis.java]"]
end

subgraph group_presentation["Results and state"]
  node_banner["Report banner<br/>[BannerPrinter.java]"]
  node_state[("Processed state")]
end

node_runtime(("Minecraft runtime"))
node_endpoint["Configured AI service"]

node_runtime -.->|"runs on"| node_fabric
node_runtime -.->|"runs on"| node_forge
node_fabric -->|"invokes"| node_analyzer
node_forge -->|"invokes"| node_analyzer
node_analyzer -->|"scans"| node_crashscan
node_analyzer -->|"reads logs"| node_logscan
node_analyzer -->|"scans"| node_hserscan
node_analyzer -->|"creates"| node_report
node_analyzer -->|"loads"| node_config
node_analyzer -->|"selects default"| node_heuristic
node_analyzer -->|"selects optionally"| node_llm
node_analyzer -->|"tracks processed"| node_state
node_analyzer -->|"prints diagnosis"| node_banner
node_heuristic -.->|"delegates to"| node_engine
node_engine -->|"dispatches rules"| node_rules
node_rules -->|"uses helpers"| node_ruleutils
node_rules -->|"implements"| node_ruleapi
node_engine -->|"returns"| node_diagnosisresult
node_llm -->|"sends request"| node_endpoint
node_llm -->|"falls back"| node_heuristic
node_llm -->|"parses result"| node_diagnosisresult
node_banner -->|"formats"| node_diagnosisresult

click node_fabric "https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/loader-fabric/src/main/java/com/yash/crashexplainer/fabric/FabricCrashExplainer.java"
click node_forge "https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/loader-forge/src/main/java/com/yash/crashexplainer/forge/ForgeEarlyService.java"
click node_analyzer "https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/CrashAnalyzer.java"
click node_crashscan "https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/CrashReportScanner.java"
click node_logscan "https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/LogFileScanner.java"
click node_hserscan "https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/HsErrScanner.java"
click node_report "https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/CrashReport.java"
click node_config "https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/ExplainerConfig.java"
click node_heuristic "https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/HeuristicExplainer.java"
click node_engine "https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/DiagnosticEngine.java"
click node_ruleapi "https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/Rule.java"
click node_rules "https://github.com/yashr-cmd/crash-explainer/tree/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/rules"
click node_ruleutils "https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/rules/CrashReportUtils.java"
click node_llm "https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/LlmExplainer.java"
click node_diagnosisresult "https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/Diagnosis.java"
click node_banner "https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/BannerPrinter.java"
click node_state "https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/ProcessedStateStore.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_fabric,node_forge toneBlue
class node_analyzer,node_crashscan,node_logscan,node_hserscan,node_report toneAmber
class node_config,node_heuristic,node_engine,node_ruleapi,node_rules,node_ruleutils,node_llm,node_diagnosisresult toneMint
class node_banner,node_state toneRose
class node_runtime,node_endpoint toneIndigo
```

## Components

### Loader integration

- [Fabric adapter](https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/loader-fabric/src/main/java/com/yash/crashexplainer/fabric/FabricCrashExplainer.java): `crashexplainer/loader-fabric/src/main/java/com/yash/crashexplainer/fabric/FabricCrashExplainer.java`
- [Forge adapter](https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/loader-forge/src/main/java/com/yash/crashexplainer/forge/ForgeEarlyService.java): `crashexplainer/loader-forge/src/main/java/com/yash/crashexplainer/forge/ForgeEarlyService.java`

### Crash intake

- [Crash analyzer](https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/CrashAnalyzer.java): `crashexplainer/core/src/main/java/com/yash/crashexplainer/core/CrashAnalyzer.java`
- [Crash report scan](https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/CrashReportScanner.java): `crashexplainer/core/src/main/java/com/yash/crashexplainer/core/CrashReportScanner.java`
- [Rotated log scan](https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/LogFileScanner.java): `crashexplainer/core/src/main/java/com/yash/crashexplainer/core/LogFileScanner.java`
- [JVM error scan](https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/HsErrScanner.java): `crashexplainer/core/src/main/java/com/yash/crashexplainer/core/HsErrScanner.java`
- [Crash report model](https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/CrashReport.java): `crashexplainer/core/src/main/java/com/yash/crashexplainer/core/CrashReport.java`

### Diagnosis

- [Explainer config](https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/ExplainerConfig.java): `crashexplainer/core/src/main/java/com/yash/crashexplainer/core/ExplainerConfig.java`
- [Heuristic explainer](https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/HeuristicExplainer.java): `crashexplainer/core/src/main/java/com/yash/crashexplainer/core/HeuristicExplainer.java`
- [Rule engine](https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/DiagnosticEngine.java): `crashexplainer/core/src/main/java/com/yash/crashexplainer/core/DiagnosticEngine.java`
- [Rule interface](https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/Rule.java): `crashexplainer/core/src/main/java/com/yash/crashexplainer/core/Rule.java`
- [Crash pattern rules](https://github.com/yashr-cmd/crash-explainer/tree/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/rules): `crashexplainer/core/src/main/java/com/yash/crashexplainer/core/rules`
- [Rule text utilities](https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/rules/CrashReportUtils.java): `crashexplainer/core/src/main/java/com/yash/crashexplainer/core/rules/CrashReportUtils.java`
- [Optional LLM explainer](https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/LlmExplainer.java): `crashexplainer/core/src/main/java/com/yash/crashexplainer/core/LlmExplainer.java`
- [Diagnosis result](https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/Diagnosis.java): `crashexplainer/core/src/main/java/com/yash/crashexplainer/core/Diagnosis.java`

### Results and state

- [Report banner](https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/BannerPrinter.java): `crashexplainer/core/src/main/java/com/yash/crashexplainer/core/BannerPrinter.java`
- [Processed state](https://github.com/yashr-cmd/crash-explainer/blob/main/crashexplainer/core/src/main/java/com/yash/crashexplainer/core/ProcessedStateStore.java): `crashexplainer/core/src/main/java/com/yash/crashexplainer/core/ProcessedStateStore.java`

### Other components

- **Minecraft runtime**
- **Configured AI service**

## Connections

- Minecraft runtime → Fabric adapter: runs on (evidence: `README.md`)
- Minecraft runtime → Forge adapter: runs on (evidence: `README.md`)
- Fabric adapter → Crash analyzer: invokes (evidence: `crashexplainer/loader-fabric/src/main/java/com/yash/crashexplainer/fabric/FabricCrashExplainer.java`)
- Forge adapter → Crash analyzer: invokes (evidence: `crashexplainer/loader-forge/src/main/java/com/yash/crashexplainer/forge/ForgeEarlyService.java`)
- Crash analyzer → Crash report scan: scans (evidence: `crashexplainer/core/src/main/java/com/yash/crashexplainer/core/CrashAnalyzer.java`)
- Crash analyzer → Rotated log scan: reads logs (evidence: `crashexplainer/core/src/main/java/com/yash/crashexplainer/core/CrashAnalyzer.java`)
- Crash analyzer → JVM error scan: scans (evidence: `crashexplainer/core/src/main/java/com/yash/crashexplainer/core/CrashAnalyzer.java`)
- Crash analyzer → Crash report model: creates (evidence: `crashexplainer/core/src/main/java/com/yash/crashexplainer/core/CrashAnalyzer.java`)
- Crash analyzer → Explainer config: loads (evidence: `crashexplainer/core/src/main/java/com/yash/crashexplainer/core/CrashAnalyzer.java`)
- Crash analyzer → Heuristic explainer: selects default (evidence: `crashexplainer/core/src/main/java/com/yash/crashexplainer/core/CrashAnalyzer.java`)
- Crash analyzer → Optional LLM explainer: selects optionally (evidence: `crashexplainer/core/src/main/java/com/yash/crashexplainer/core/CrashAnalyzer.java`)
- Crash analyzer → Processed state: tracks processed (evidence: `crashexplainer/core/src/main/java/com/yash/crashexplainer/core/CrashAnalyzer.java`)
- Crash analyzer → Report banner: prints diagnosis (evidence: `crashexplainer/core/src/main/java/com/yash/crashexplainer/core/CrashAnalyzer.java`)
- Heuristic explainer → Rule engine: delegates to (evidence: `crashexplainer/core/src/main/java/com/yash/crashexplainer/core/HeuristicExplainer.java`)
- Rule engine → Crash pattern rules: dispatches rules (evidence: `crashexplainer/core/src/main/java/com/yash/crashexplainer/core/DiagnosticEngine.java`)
- Crash pattern rules → Rule text utilities: uses helpers (evidence: `crashexplainer/core/src/main/java/com/yash/crashexplainer/core/rules/MixinApplyFailureRule.java`)
- Crash pattern rules → Rule interface: implements (evidence: `crashexplainer/core/src/main/java/com/yash/crashexplainer/core/rules/MixinApplyFailureRule.java`)
- Rule engine → Diagnosis result: returns (evidence: `crashexplainer/core/src/main/java/com/yash/crashexplainer/core/DiagnosticEngine.java`)
- Optional LLM explainer → Configured AI service: sends request (evidence: `crashexplainer/core/src/main/java/com/yash/crashexplainer/core/LlmExplainer.java`)
- Optional LLM explainer → Heuristic explainer: falls back (evidence: `crashexplainer/core/src/main/java/com/yash/crashexplainer/core/LlmExplainer.java`)
- Optional LLM explainer → Diagnosis result: parses result (evidence: `crashexplainer/core/src/main/java/com/yash/crashexplainer/core/LlmExplainer.java`)
- Report banner → Diagnosis result: formats (evidence: `crashexplainer/core/src/main/java/com/yash/crashexplainer/core/BannerPrinter.java`)