# driw0x/cs2guard architecture

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

- Interactive diagram: https://gitdiagram.com/driw0x/cs2guard
- Repository: https://github.com/driw0x/cs2guard

## Overview

CS2Guard is an experimental offline behavioral-cheat analysis toolkit for Counter-Strike 2 demos and external datasets. Its documented workflow parses match telemetry, derives aim behavior, builds normalized and labeled datasets, then evaluates anomaly or supervised detectors to produce event/player suspicion scores. The tree also includes aim visualization and player inspection tools. The README describes real-time server-side detection as a future goal, not a current runtime subsystem. Some wiring is based on documented capabilities and module names because the relevant scripts and implementation details were not sampled.

Main entry points: [`demo_analyzer/src/cs2guard_demo/dataset/builder.py`](https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/dataset/builder.py) (Dataset Builder), [`demo_analyzer/src/cs2guard_demo/parser/demo_parser.py`](https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/parser/demo_parser.py) (Demo Parser), [`demo_analyzer/src/cs2guard_demo/supervised/models.py`](https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/supervised/models.py) (Classifiers), [`demo_analyzer/src/cs2guard_demo/dataset/adapters/demo.py`](https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/dataset/adapters/demo.py) (Demo Adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Telemetry Ingestion"]
  node_parser["Demo Parser<br/>[demo_parser.py]"]
  node_game_models["Match Models<br/>[match.py]"]
  node_aim_features["Aim Features<br/>[aim.py]"]
end

subgraph group_dataset["Dataset Preparation"]
  node_demo_adapter["Demo Adapter<br/>[demo.py]"]
  node_cs2cd_adapter["CS2CD Adapter<br/>[cs2cd.py]"]
  node_dataset_builder["Dataset Builder<br/>[builder.py]"]
  node_canonical_schema["Canonical Schema<br/>[schema.py]"]
  node_labels["Labels<br/>[labels.py]"]
  node_normalization["Normalization<br/>[normalization.py]"]
  node_splitter["Data Splits<br/>[splitting.py]"]
end

subgraph group_detection["Detection Models"]
  node_anomaly["Anomaly Detection<br/>[anomaly.py]"]
  node_supervised_data["Supervised Dataset<br/>[dataset.py]"]
  node_supervised_models["Classifiers<br/>[models.py]"]
  node_tuning["Model Tuning<br/>[tuning.py]"]
  node_evaluation["Model Evaluation<br/>[evaluation.py]"]
  node_persistence["Model Persistence<br/>[persistence.py]"]
end

subgraph group_analysis["Analysis Outputs"]
  node_score_analysis["Suspicion Analysis"]
  node_aim_visualization["Aim Visualization<br/>[aim.py]"]
  node_player_inspection["Player Inspection<br/>[inspect_player.py]"]
end

node_analyst(("Analyst"))
node_demo_file["CS2 Demo"]
node_cs2cd_data["CS2CD Data"]

node_analyst -->|"supplies"| node_demo_file
node_demo_file -->|"parses"| node_parser
node_parser -->|"structures data"| node_game_models
node_parser -->|"provides telemetry"| node_aim_features
node_demo_file -->|"adapts source"| node_demo_adapter
node_parser -->|"reads match data"| node_demo_adapter
node_cs2cd_data -->|"adapts source"| node_cs2cd_adapter
node_demo_adapter -->|"validates rows"| node_canonical_schema
node_cs2cd_adapter -->|"validates rows"| node_canonical_schema
node_demo_adapter -->|"provides samples"| node_dataset_builder
node_cs2cd_adapter -->|"provides samples"| node_dataset_builder
node_aim_features -->|"engineers features"| node_dataset_builder
node_dataset_builder -->|"adds labels"| node_labels
node_dataset_builder -->|"prepares features"| node_normalization
node_dataset_builder -->|"creates splits"| node_splitter
node_dataset_builder -->|"supplies features"| node_anomaly
node_splitter -->|"supplies partitions"| node_supervised_data
node_supervised_data -->|"supplies training data"| node_supervised_models
node_supervised_models -->|"tunes classifiers"| node_tuning
node_supervised_models -->|"evaluates predictions"| node_evaluation
node_supervised_models -->|"saves models"| node_persistence
node_anomaly -->|"provides anomaly scores"| node_score_analysis
node_evaluation -->|"provides model metrics"| node_score_analysis
node_parser -.->|"provides aim sequences"| node_aim_visualization
node_score_analysis -->|"supports review"| node_player_inspection
node_aim_visualization -->|"displays trajectories"| node_analyst
node_player_inspection -->|"presents findings"| node_analyst

click node_parser "https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/parser/demo_parser.py"
click node_game_models "https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/models/match.py"
click node_aim_features "https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/features/aim.py"
click node_demo_adapter "https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/dataset/adapters/demo.py"
click node_cs2cd_adapter "https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/dataset/adapters/cs2cd.py"
click node_dataset_builder "https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/dataset/builder.py"
click node_canonical_schema "https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/dataset/schema.py"
click node_labels "https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/dataset/labels.py"
click node_normalization "https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/dataset/normalization.py"
click node_splitter "https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/dataset/splitting.py"
click node_anomaly "https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/detection/anomaly.py"
click node_supervised_data "https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/supervised/dataset.py"
click node_supervised_models "https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/supervised/models.py"
click node_tuning "https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/supervised/tuning.py"
click node_evaluation "https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/supervised/evaluation.py"
click node_persistence "https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/supervised/persistence.py"
click node_score_analysis "https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/scripts/generate_suspicion_scores.py"
click node_aim_visualization "https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/visualization/aim.py"
click node_player_inspection "https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/scripts/inspect_player.py"

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_parser,node_game_models,node_aim_features toneBlue
class node_demo_adapter,node_cs2cd_adapter,node_dataset_builder,node_canonical_schema,node_labels,node_normalization,node_splitter toneAmber
class node_anomaly,node_supervised_data,node_supervised_models,node_tuning,node_evaluation,node_persistence toneMint
class node_score_analysis,node_aim_visualization,node_player_inspection toneRose
class node_analyst,node_demo_file,node_cs2cd_data toneIndigo
```

## Components

### Telemetry Ingestion

- [Demo Parser](https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/parser/demo_parser.py): `demo_analyzer/src/cs2guard_demo/parser/demo_parser.py`
- [Match Models](https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/models/match.py): `demo_analyzer/src/cs2guard_demo/models/match.py`
- [Aim Features](https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/features/aim.py): `demo_analyzer/src/cs2guard_demo/features/aim.py`

### Dataset Preparation

- [Demo Adapter](https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/dataset/adapters/demo.py): `demo_analyzer/src/cs2guard_demo/dataset/adapters/demo.py`
- [CS2CD Adapter](https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/dataset/adapters/cs2cd.py): `demo_analyzer/src/cs2guard_demo/dataset/adapters/cs2cd.py`
- [Dataset Builder](https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/dataset/builder.py): `demo_analyzer/src/cs2guard_demo/dataset/builder.py`
- [Canonical Schema](https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/dataset/schema.py): `demo_analyzer/src/cs2guard_demo/dataset/schema.py`
- [Labels](https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/dataset/labels.py): `demo_analyzer/src/cs2guard_demo/dataset/labels.py`
- [Normalization](https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/dataset/normalization.py): `demo_analyzer/src/cs2guard_demo/dataset/normalization.py`
- [Data Splits](https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/dataset/splitting.py): `demo_analyzer/src/cs2guard_demo/dataset/splitting.py`

### Detection Models

- [Anomaly Detection](https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/detection/anomaly.py): `demo_analyzer/src/cs2guard_demo/detection/anomaly.py`
- [Supervised Dataset](https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/supervised/dataset.py): `demo_analyzer/src/cs2guard_demo/supervised/dataset.py`
- [Classifiers](https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/supervised/models.py): `demo_analyzer/src/cs2guard_demo/supervised/models.py`
- [Model Tuning](https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/supervised/tuning.py): `demo_analyzer/src/cs2guard_demo/supervised/tuning.py`
- [Model Evaluation](https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/supervised/evaluation.py): `demo_analyzer/src/cs2guard_demo/supervised/evaluation.py`
- [Model Persistence](https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/supervised/persistence.py): `demo_analyzer/src/cs2guard_demo/supervised/persistence.py`

### Analysis Outputs

- [Suspicion Analysis](https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/scripts/generate_suspicion_scores.py): `demo_analyzer/scripts/generate_suspicion_scores.py`
- [Aim Visualization](https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/src/cs2guard_demo/visualization/aim.py): `demo_analyzer/src/cs2guard_demo/visualization/aim.py`
- [Player Inspection](https://github.com/driw0x/cs2guard/blob/main/demo_analyzer/scripts/inspect_player.py): `demo_analyzer/scripts/inspect_player.py`

### Other components

- **Analyst**
- **CS2 Demo**
- **CS2CD Data**

## Connections

- Analyst → CS2 Demo: supplies
- CS2 Demo → Demo Parser: parses
- Demo Parser → Match Models: structures data
- Demo Parser → Aim Features: provides telemetry
- CS2 Demo → Demo Adapter: adapts source
- Demo Parser → Demo Adapter: reads match data
- CS2CD Data → CS2CD Adapter: adapts source
- Demo Adapter → Canonical Schema: validates rows
- CS2CD Adapter → Canonical Schema: validates rows
- Demo Adapter → Dataset Builder: provides samples
- CS2CD Adapter → Dataset Builder: provides samples
- Aim Features → Dataset Builder: engineers features
- Dataset Builder → Labels: adds labels
- Dataset Builder → Normalization: prepares features
- Dataset Builder → Data Splits: creates splits
- Dataset Builder → Anomaly Detection: supplies features
- Data Splits → Supervised Dataset: supplies partitions
- Supervised Dataset → Classifiers: supplies training data
- Classifiers → Model Tuning: tunes classifiers
- Classifiers → Model Evaluation: evaluates predictions
- Classifiers → Model Persistence: saves models
- Anomaly Detection → Suspicion Analysis: provides anomaly scores
- Model Evaluation → Suspicion Analysis: provides model metrics
- Demo Parser → Aim Visualization: provides aim sequences
- Suspicion Analysis → Player Inspection: supports review
- Aim Visualization → Analyst: displays trajectories
- Player Inspection → Analyst: presents findings