# hlnd2t/goldsrc_vibesignatures architecture

> Architecture diagram of the GitHub repository hlnd2t/goldsrc_vibesignatures, 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/hlnd2t/goldsrc_vibesignatures
- Repository: https://github.com/hlnd2t/goldsrc_vibesignatures

## Overview

GoldSrc VibeSignatures is a reproducible GoldSrc binary-analysis framework. The main workflow acquires game binaries, restores exact warm IDB generations, runs IDA-backed symbol analysis, and produces per-symbol YAML artifacts; snapshot tooling validates and packages artifacts, while PR tooling plans their impact. The repository also documents process reporting and a dashboard for run monitoring, plus symbol search. Dashboard backend implementation and several workflow details were not sampled, so those connections are limited to documented capabilities rather than inferred calls.

Main entry points: [`ida_analyze_bin.py`](https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/ida_analyze_bin.py) (IDA analyzer), [`gamesymbol_snapshot_lib/operations.py`](https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/gamesymbol_snapshot_lib/operations.py) (Snapshot operations), [`pages/src/App.tsx`](https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/pages/src/App.tsx) (Dashboard UI), [`release_workflow_lib/accepted_bin.py`](https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/release_workflow_lib/accepted_bin.py) (Accepted binaries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_acquisition["Binary acquisition"]
  node_depot["Depot download<br/>[download_depot.py]"]
  node_binary["Game binaries<br/>[binary_format.py]"]
  node_warm["Warm IDB restore<br/>[idb_warm_worker.py]"]
end

subgraph group_analysis["Symbol analysis"]
  node_config["Analysis config<br/>[analysis_config.py]"]
  node_analyzer["IDA analyzer<br/>[ida_analyze_bin.py]"]
  node_ida_util["IDA analysis utilities"]
  node_decompile["LLM decompiler"]
  node_llm_spec["Decompile specs<br/>[llm_spec.py]"]
  node_declarations["Symbol declarations"]
  node_preprocessors["Symbol preprocessors"]
  node_direct_gv["Global references"]
end

subgraph group_artifacts["Artifacts and snapshots"]
  node_artifacts["Symbol YAML artifacts<br/>[operations.py]"]
  node_contract["Artifact contract"]
  node_diagnostics["Artifact diagnostics"]
  node_snapshot["Snapshot operations<br/>[operations.py]"]
  node_snapshot_model["Snapshot model<br/>[model.py]"]
  node_snapshot_paths["Snapshot paths<br/>[paths.py]"]
  node_anchor_drift["Anchor drift<br/>[anchor_drift.py]"]
end

subgraph group_workflow["Release and PR workflow"]
  node_pr_plan["PR impact planning<br/>[pr_cli.py]"]
  node_release["Accepted binaries<br/>[accepted_bin.py]"]
  node_release_hash["Release hashing<br/>[hashing.py]"]
  node_release_manifest["Release manifests<br/>[manifests.py]"]
end

subgraph group_dashboard["Run dashboard"]
  node_dashboard["Dashboard UI<br/>[App.tsx]"]
  node_run_detail["Live run view<br/>[useRunLive.ts]"]
  node_api_client["Dashboard API client<br/>[client.ts]"]
  node_symbol_search["Symbol search<br/>[SymbolSearch.tsx]"]
end

node_user(("Engineer"))
node_api_service["Process monitoring API"]
node_llm_service["LLM service"]

node_user -->|"acquires binaries"| node_depot
node_depot -.->|"downloads"| node_binary
node_binary -->|"restores IDBs"| node_warm
node_user -->|"starts analysis"| node_analyzer
node_config -->|"configures"| node_analyzer
node_analyzer -->|"uses"| node_ida_util
node_ida_util -->|"invokes"| node_decompile
node_decompile -.->|"requests analysis"| node_llm_service
node_analyzer -.->|"uses specs"| node_declarations
node_analyzer -.->|"runs skills"| node_preprocessors
node_preprocessors -->|"uses helpers"| node_direct_gv
node_analyzer -->|"writes YAML"| node_artifacts
node_artifacts -->|"validated by"| node_contract
node_contract -->|"reports issues"| node_diagnostics
node_user -->|"packs or verifies"| node_snapshot
node_snapshot -->|"builds snapshot"| node_snapshot_model
node_snapshot -->|"resolves paths"| node_snapshot_paths
node_snapshot -->|"checks anchors"| node_anchor_drift
node_user -->|"plans PR impact"| node_pr_plan
node_pr_plan -->|"materializes artifacts"| node_snapshot
node_release -->|"verifies files"| node_release_hash
node_release -->|"uses manifests"| node_release_manifest
node_user -->|"views runs"| node_dashboard
node_dashboard -.->|"shows run detail"| node_run_detail
node_run_detail -->|"requests run data"| node_api_client
node_api_client -->|"fetches and streams"| node_api_service
node_dashboard -.->|"searches symbols"| node_symbol_search

click node_depot "https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/download_depot.py"
click node_binary "https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/binary_format.py"
click node_warm "https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/idb_warm_worker.py"
click node_config "https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/analysis_config.py"
click node_analyzer "https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/ida_analyze_bin.py"
click node_ida_util "https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/ida_analyze_util.py"
click node_decompile "https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/ida_llm_decompile.py"
click node_llm_spec "https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/llm_spec.py"
click node_declarations "https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/llm_declarations.py"
click node_preprocessors "https://github.com/hlnd2t/goldsrc_vibesignatures/tree/main/ida_preprocessor_scripts"
click node_direct_gv "https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/ida_preprocessor_scripts/_direct_gv_common.py"
click node_artifacts "https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/gamesymbol_snapshot_lib/operations.py"
click node_contract "https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/bin_artifact_contract.py"
click node_diagnostics "https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/artifact_diagnostics.py"
click node_snapshot "https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/gamesymbol_snapshot_lib/operations.py"
click node_snapshot_model "https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/gamesymbol_snapshot_lib/model.py"
click node_snapshot_paths "https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/gamesymbol_snapshot_lib/paths.py"
click node_anchor_drift "https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/gamesymbol_snapshot_lib/anchor_drift.py"
click node_pr_plan "https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/gamesymbol_snapshot_lib/pr_cli.py"
click node_release "https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/release_workflow_lib/accepted_bin.py"
click node_release_hash "https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/release_workflow_lib/hashing.py"
click node_release_manifest "https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/release_workflow_lib/manifests.py"
click node_dashboard "https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/pages/src/App.tsx"
click node_run_detail "https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/pages/src/features/run-detail/useRunLive.ts"
click node_api_client "https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/pages/src/api/client.ts"
click node_symbol_search "https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/pages/src/features/symbols/SymbolSearch.tsx"

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_depot,node_binary,node_warm toneBlue
class node_config,node_analyzer,node_ida_util,node_decompile,node_llm_spec,node_declarations,node_preprocessors,node_direct_gv toneAmber
class node_artifacts,node_contract,node_diagnostics,node_snapshot,node_snapshot_model,node_snapshot_paths,node_anchor_drift,node_api_service toneMint
class node_pr_plan,node_release,node_release_hash,node_release_manifest toneRose
class node_dashboard,node_run_detail,node_api_client,node_symbol_search,node_user,node_llm_service toneIndigo
```

## Components

### Binary acquisition

- [Depot download](https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/download_depot.py): `download_depot.py`
- [Game binaries](https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/binary_format.py): `binary_format.py`
- [Warm IDB restore](https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/idb_warm_worker.py): `idb_warm_worker.py`

### Symbol analysis

- [Analysis config](https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/analysis_config.py): `analysis_config.py`
- [IDA analyzer](https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/ida_analyze_bin.py): `ida_analyze_bin.py`
- [IDA analysis utilities](https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/ida_analyze_util.py): `ida_analyze_util.py`
- [LLM decompiler](https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/ida_llm_decompile.py): `ida_llm_decompile.py`
- [Decompile specs](https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/llm_spec.py): `llm_spec.py`
- [Symbol declarations](https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/llm_declarations.py): `llm_declarations.py`
- [Symbol preprocessors](https://github.com/hlnd2t/goldsrc_vibesignatures/tree/main/ida_preprocessor_scripts): `ida_preprocessor_scripts`
- [Global references](https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/ida_preprocessor_scripts/_direct_gv_common.py): `ida_preprocessor_scripts/_direct_gv_common.py`

### Artifacts and snapshots

- [Symbol YAML artifacts](https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/gamesymbol_snapshot_lib/operations.py): `gamesymbol_snapshot_lib/operations.py`
- [Artifact contract](https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/bin_artifact_contract.py): `bin_artifact_contract.py`
- [Artifact diagnostics](https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/artifact_diagnostics.py): `artifact_diagnostics.py`
- [Snapshot operations](https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/gamesymbol_snapshot_lib/operations.py): `gamesymbol_snapshot_lib/operations.py`
- [Snapshot model](https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/gamesymbol_snapshot_lib/model.py): `gamesymbol_snapshot_lib/model.py`
- [Snapshot paths](https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/gamesymbol_snapshot_lib/paths.py): `gamesymbol_snapshot_lib/paths.py`
- [Anchor drift](https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/gamesymbol_snapshot_lib/anchor_drift.py): `gamesymbol_snapshot_lib/anchor_drift.py`

### Release and PR workflow

- [PR impact planning](https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/gamesymbol_snapshot_lib/pr_cli.py): `gamesymbol_snapshot_lib/pr_cli.py`
- [Accepted binaries](https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/release_workflow_lib/accepted_bin.py): `release_workflow_lib/accepted_bin.py`
- [Release hashing](https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/release_workflow_lib/hashing.py): `release_workflow_lib/hashing.py`
- [Release manifests](https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/release_workflow_lib/manifests.py): `release_workflow_lib/manifests.py`

### Run dashboard

- [Dashboard UI](https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/pages/src/App.tsx): `pages/src/App.tsx`
- [Live run view](https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/pages/src/features/run-detail/useRunLive.ts): `pages/src/features/run-detail/useRunLive.ts`
- [Dashboard API client](https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/pages/src/api/client.ts): `pages/src/api/client.ts`
- [Symbol search](https://github.com/hlnd2t/goldsrc_vibesignatures/blob/main/pages/src/features/symbols/SymbolSearch.tsx): `pages/src/features/symbols/SymbolSearch.tsx`

### Other components

- **Engineer**
- **Process monitoring API**
- **LLM service**

## Connections

- Engineer → Depot download: acquires binaries (evidence: `README.md`)
- Depot download → Game binaries: downloads
- Game binaries → Warm IDB restore: restores IDBs (evidence: `README.md`)
- Engineer → IDA analyzer: starts analysis (evidence: `README.md`)
- Analysis config → IDA analyzer: configures (evidence: `analysis_config.py`)
- IDA analyzer → IDA analysis utilities: uses (evidence: `ida_analyze_util.py`)
- IDA analysis utilities → LLM decompiler: invokes (evidence: `ida_analyze_util.py`)
- LLM decompiler → LLM service: requests analysis
- IDA analyzer → Symbol declarations: uses specs
- IDA analyzer → Symbol preprocessors: runs skills (evidence: `README.md`)
- Symbol preprocessors → Global references: uses helpers (evidence: `ida_preprocessor_scripts/find-EngineSurface-context-globals.py`)
- IDA analyzer → Symbol YAML artifacts: writes YAML (evidence: `README.md`)
- Symbol YAML artifacts → Artifact contract: validated by (evidence: `bin_artifact_contract.py`)
- Artifact contract → Artifact diagnostics: reports issues (evidence: `bin_artifact_contract.py`)
- Engineer → Snapshot operations: packs or verifies (evidence: `README.md`)
- Snapshot operations → Snapshot model: builds snapshot (evidence: `gamesymbol_snapshot_lib/operations.py`)
- Snapshot operations → Snapshot paths: resolves paths (evidence: `gamesymbol_snapshot_lib/operations.py`)
- Snapshot operations → Anchor drift: checks anchors (evidence: `bin_artifact_contract.py`)
- Engineer → PR impact planning: plans PR impact (evidence: `README.md`)
- PR impact planning → Snapshot operations: materializes artifacts (evidence: `gamesymbol_snapshot_lib/pr_cli.py`)
- Accepted binaries → Release hashing: verifies files (evidence: `release_workflow_lib/accepted_bin.py`)
- Accepted binaries → Release manifests: uses manifests (evidence: `release_workflow_lib/accepted_bin.py`)
- Engineer → Dashboard UI: views runs (evidence: `README.md`)
- Dashboard UI → Live run view: shows run detail
- Live run view → Dashboard API client: requests run data (evidence: `pages/src/features/run-detail/useRunLive.ts`)
- Dashboard API client → Process monitoring API: fetches and streams (evidence: `pages/src/api/client.ts`)
- Dashboard UI → Symbol search: searches symbols
