# shahriar0651/canshield architecture

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

- Interactive diagram: https://gitdiagram.com/shahriar0651/canshield
- Repository: https://github.com/shahriar0651/canshield

## Overview

##### Project Type and Purpose
- CANShield is a research-oriented deep learning system designed for intrusion detection on the CAN bus. It processes high-dimensional CAN signals and applies multiple deep autoencoders to extract temporal features from different scales before combining results through an ensemble detection mechanism.
- The README explicitly mentions the three stages: (a) data preprocessing, (b) deep autoencoder analysis (training), and (c) attack detection (ensemble decision-making). Supplementary components include evaluation and visualization of results.

##### Main Components
a. Environment & Configuration:
- Dependency management and configuration aspect. This includes:
- “dependency” folder containing environment YAML files (environment_v1.yaml, environment_v2.yaml).
- “config” folder with different configuration files (road.yaml, syncan.yaml).
- As a “Configuration/Environment” block that feeds into the rest of the system.

b. Data Acquisition and Preprocessing:

c. Model Training (Autoencoder Training):
- A “Training Module” that includes:
- The training scripts (train_autoencoder.py) and helper functions (get_autoencoder.py).
- A clear linkage to the preprocessed data and the configuration (modules under src/training).
- How this module trains different autoencoders over various temporal granularities.

d. Model Evaluation:
- An “Evaluation Module” represented by run_evaluation_canshield.py and the testing utilities found in src/testing (e.g., load_predictions.py, load_thresholds.py). This module takes the trained model and evaluates its performance on test datasets (both continuous and partial).
- Feedback loop to compare predicted intrusion scores against ground truth.

e. Visualization:

##### Relationships and Interactions
- From the “Data Acquisition” to “Preprocessing” module.
- From “Preprocessing” to “Training.”
- From “Training” to “Evaluation” and then onward to “Visualization.”
- The “Configuration/Environment” component should have connections pointing to every module that depends on these settings (training, evaluation, etc.).
- The “Dependency” and “Config” components should also be highlighted as integral to ensuring consistency across different computation setups (as noted in the README).

##### Architectural Patterns and Design Principles
- The system is modular: separating concerns into clearly defined blocks (data processing, training, evaluation, and visualization).
- It leverages a pipeline-like flow: raw data is cleaned and processed, then used to train multiple specialized models, subsequently evaluated, and finally visualized.
- Use of external tools (shell scripting for dataset download, configuration via YAML files, and Jupyter Notebook for model preprocessing) that all need to be reflected in the architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Configuration/Environment Subgraph
    subgraph "Configuration/Environment"
        DEP1("Dependency File"):::config
        DEP2("Dependency File"):::config
        CFG1("Config File"):::config
        CFG2("Config File"):::config
    end

    %% Data Acquisition Subgraph
    subgraph "Data Acquisition"
        DA1("Download Script"):::acquire
    end

    %% Data Preprocessing Subgraph
    subgraph "Data Preprocessing"
        DP1("Preprocessing Notebook"):::preproc
        DP2("Dataset Loader"):::preproc
    end

    %% Model Training (Autoencoder Training) Subgraph
    subgraph "Model Training (Autoencoder Training)"
        MT1("Train Autoencoder"):::training
        MT2("Autoencoder Helper"):::training
    end

    %% Ensemble Attack Detection (Internal Step)
    EA("Ensemble Attack Detection"):::ensemble

    %% Model Evaluation Subgraph
    subgraph "Model Evaluation"
        ME1("Run Evaluation"):::evaluation
        ME2("Testing Utilities"):::evaluation
    end

    %% Visualization Subgraph
    subgraph "Visualization"
        V1("Run Visualization"):::visual
        V2("Visualize Functions"):::visual
    end

    %% Workflow Connections
    DA1 -->|"CAN_Signals"| DP1
    DP1 -->|"Preprocessed_Data"| MT1
    MT1 -->|"ensemble"| EA
    EA -->|"detection_results"| ME1
    ME1 -->|"Evaluation_Metrics"| V1

    %% Configuration Influence Connections (using representative config nodes)
    DEP1 -->|"config"| DA1
    DEP1 -->|"config"| DP1
    DEP1 -->|"config"| MT1
    DEP1 -->|"config"| ME1
    DEP1 -->|"config"| V1

    CFG1 -->|"config"| DA1
    CFG1 -->|"config"| DP1
    CFG1 -->|"config"| MT1
    CFG1 -->|"config"| ME1
    CFG1 -->|"config"| V1

    %% Class definitions for color coding
    classDef config fill:#B3E5FC,stroke:#0277BD,stroke-width:2px,color:#000;
    classDef acquire fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px,color:#000;
    classDef preproc fill:#C8E6C9,stroke:#388E3C,stroke-width:2px,color:#000;
    classDef training fill:#FFCDD2,stroke:#D32F2F,stroke-width:2px,color:#000;
    classDef ensemble fill:#D1C4E9,stroke:#7B1FA2,stroke-width:2px,color:#000;
    classDef evaluation fill:#F0F4C3,stroke:#AFB42B,stroke-width:2px,color:#000;
    classDef visual fill:#FFECB3,stroke:#FFA000,stroke-width:2px,color:#000;

    %% Click Events for Configuration/Environment
    click DEP1 "https://github.com/shahriar0651/canshield/blob/main/dependency/environment_v1.yaml"
    click DEP2 "https://github.com/shahriar0651/canshield/blob/main/dependency/environment_v2.yaml"
    click CFG1 "https://github.com/shahriar0651/canshield/blob/main/config/road.yaml"
    click CFG2 "https://github.com/shahriar0651/canshield/blob/main/config/syncan.yaml"

    %% Click Events for Data Acquisition
    click DA1 "https://github.com/shahriar0651/canshield/blob/main/src/download_syncan_dataset.sh"

    %% Click Events for Data Preprocessing
    click DP1 "https://github.com/shahriar0651/canshield/blob/main/src/Model_Preprocessing.ipynb"
    click DP2 "https://github.com/shahriar0651/canshield/tree/main/src/dataset/"

    %% Click Events for Model Training
    click MT1 "https://github.com/shahriar0651/canshield/blob/main/src/training/train_autoencoder.py"
    click MT2 "https://github.com/shahriar0651/canshield/blob/main/src/training/get_autoencoder.py"

    %% Click Events for Model Evaluation
    click ME1 "https://github.com/shahriar0651/canshield/blob/main/src/run_evaluation_canshield.py"
    click ME2 "https://github.com/shahriar0651/canshield/tree/main/src/testing/"

    %% Click Events for Visualization
    click V1 "https://github.com/shahriar0651/canshield/blob/main/src/run_visualization_results.py"
    click V2 "https://github.com/shahriar0651/canshield/blob/main/src/visualize/visualize_functions.py"
```
