# filipholik/smartgridsim architecture

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

- Interactive diagram: https://gitdiagram.com/filipholik/smartgridsim
- Repository: https://github.com/filipholik/smartgridsim

## Overview

##### Project Type and Purpose
- SGSim is a full-stack simulation tool for smart-grid communications and cyber-attack emulation.
- Key runtime modes:
– Network emulation via Mininet (Python scripts)
– Desktop GUI app (C)
– Browser-based SCADA GUI (PHP + JavaScript)
– Data persistence (SQLite)

##### File Structure
Top-level items:
- Start scripts:
– StartSGTopology.sh / StartDSSTopology.sh → bootstraps Mininet topologies
– StartGUI.sh → compiles & runs the C desktop GUI
– initDatabase.sh → initializes the SQLite schema
- topologies/
– SmartGridTopology.py, DSSTopology.py → define Mininet graphs and attach device emulators
- comlib_dps.zip, comlib_dss.zip
– Device-simulation libraries for primary/secondary substations, unpacked by the topology scripts
- GUI/
– Application/ → C source (GUI.c), CMakeLists.txt, styling (style.css)
– PHPserver/ → SCADA web server (PHP pages, CSS, JS, SQLite DB file, dbHandler modules)
– DDOSDetection.sh → shell script to detect flood attacks in the emulated network
- GUI/PHPserver/dbHandler/
– PHP modules that connect to SGData.db and expose sensor values, timestamps, DDOS flags, GOOSE states, etc.

##### README for Stack Details
- Dependencies: mininet, sqlite3, PHP
- Workflow:
1. Unzip comlib packages
2. Run “StartSGTopology.sh” (mininet + Python)
3. Run “GUI/StartGUI.sh” (desktop GUI)
4. Browse to localhost:8000 for web SCADA
- Two GUIs operate in parallel: desktop C app and browser SCADA

##### Main Components & Their Interactions
A. Host Environment
– Shell scripts orchestrate startup (topology, GUI, DB init)
B. Network Emulator (Mininet + Python)
– Python topologies spawn hosts representing IEDs, sensors, IED1…IED4, DSS1…DSS2
– Each host loads comlib_dps or comlib_dss to simulate IEC 61850 traffic (GOOSE, SV, MMS)
– A DDOSDetection.sh script runs on one host (or controller) to monitor flood attacks
C. Data Storage (SQLite)
– initDatabase.sh creates SGData.db
– Device-simulation code writes measurement and state data via HTTP calls to PHPserver/dbHandler/*.php
– DDOSDetection.sh writes anomaly flags to SGData.db
D. Web SCADA Server (PHP + JavaScript)
– index.php + client.js + topology.js render real-time substation topology and values in a browser
– dbHandler modules serve JSON endpoints for sensor data, timestamps, GOOSE states
E. Desktop GUI (C app)
– Compiled under GUI/Application via CMake / Makefile
– Polls SGData.db directly or via HTTP endpoints to display network & data in a native window

##### Architectural Patterns & Principles
- Separation of concerns:
– Network emulation, data capture, data storage, web UI, desktop UI are decoupled
- MVC in Web SCADA:
– Model: SGData.db + dbHandler PHP scripts
– View: HTML/CSS/JavaScript (topology.js, client.js)
– Controller: PHP pages
- Micro-process style: each shell script, Python script, PHP module performs a single role

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Orchestration Layer
    subgraph "Orchestration Scripts"
        direction TB
        StartSG["StartSGTopology.sh"]:::orchestration
        StartDSS["StartDSSTopology.sh"]:::orchestration
        InitDB["initDatabase.sh"]:::orchestration
        StartGUI["StartGUI.sh"]:::orchestration
    end

    %% Network Emulation Layer
    subgraph "Network Emulation" 
        direction TB
        Mininet["Mininet Controller + Python Topology"]:::network
        Devices["Device Simulators\n(comlib_dps, comlib_dss)"]:::network
        DDOS["DDOSDetection.sh"]:::network
    end

    %% Data Layer
    subgraph "Data Persistence"
        direction TB
        DB["SGData.db"]:::data
    end

    %% Presentation Layer
    subgraph "Web SCADA"
        direction TB
        Apache["Apache/PHP Server"]:::web
        Index["index.php + style.css"]:::web
        subgraph "Topology UI" 
            direction TB
            TopPHP["topology.php"]:::web
            TopJS["topology.js"]:::web
            TopStyle["style.css"]:::web
            TopData["data.json"]:::web
            subgraph "Topology Scripts & Icons"
                Connect1["connect_DSS1.sh"]:::web
                Connect2["connect_DSS2.sh"]:::web
                Disc1["disconnect_DSS1.sh"]:::web
                Disc2["disconnect_DSS2.sh"]:::web
                Icons["icon/"]:::web
            end
        end
        subgraph "Admin Panel"
            direction TB
            AdminPHP["adminpanel.php"]:::web
            AdminJS["client.js"]:::web
        end
        subgraph "DB Handler (Model)"
            direction TB
            Conn["connectDb.php"]:::web
            DSS1Val["DSS1sensorValue.php"]:::web
            DSS1Time["DSS1sensorTimestamp.php"]:::web
            DSS2Val["DSS2sensorValue.php"]:::web
            DSS2Time["DSS2sensorTimestamp.php"]:::web
            IED1GVal["IED1gooseValue.php"]:::web
            IED1GState["IED1gooseState.php"]:::web
            IED2SV["IED2svValue.php"]:::web
            IED3SVVal["IED3svValue.php"]:::web
            IED3SVState["IED3svState.php"]:::web
            IED4GVal["IED4gooseValue.php"]:::web
            IED4GState["IED4gooseState.php"]:::web
            GOOSETime["GOOSETimestamp.php"]:::web
            TimeStamp["timestamp.php"]:::web
            ASDU["asdu.php"]:::web
            State["state.php"]:::web
            PortConn["portConnected.php"]:::web
            DDOSMod["DDOS.php"]:::web
        end
        Browser["SCADA UI (JS/CSS)"]:::web
    end

    subgraph "Desktop GUI"
        direction TB
        GTK["C GTK GUI"]:::desktop
    end

    %% Connections
    StartSG -->|boots topology| Mininet
    StartDSS -->|boots DSS topology| Mininet
    Mininet -->|loads comlib libraries| Devices
    Devices -->|POST data| Conn
    DDOS -->|writes anomaly flags| DB
    InitDB -->|creates schema| DB
    Conn -->|writes data| DB
    Apache -->|reads DB| DB
    Browser -->|AJAX JSON| Apache
    GTK -->|reads DB or HTTP| DB

    %% Click Events
    click StartSG "https://github.com/filipholik/smartgridsim/blob/main//StartSGTopology.sh"
    click StartDSS "https://github.com/filipholik/smartgridsim/blob/main//StartDSSTopology.sh"
    click InitDB "https://github.com/filipholik/smartgridsim/blob/main//GUI/initDatabase.sh"
    click StartGUI "https://github.com/filipholik/smartgridsim/blob/main//GUI/StartGUI.sh"
    click Mininet "https://github.com/filipholik/smartgridsim/blob/main//topologies/SmartGridTopology.py"
    click Mininet "https://github.com/filipholik/smartgridsim/blob/main//topologies/DSSTopology.py"
    click Devices "https://github.com/filipholik/smartgridsim/blob/main//comlib_dps.zip"
    click Devices "https://github.com/filipholik/smartgridsim/blob/main//comlib_dss.zip"
    click DDOS "https://github.com/filipholik/smartgridsim/blob/main//GUI/DDOSDetection.sh"
    click DB "https://github.com/filipholik/smartgridsim/blob/main//GUI/PHPserver/SGData.db"
    click Index "https://github.com/filipholik/smartgridsim/blob/main//GUI/PHPserver/index.php"
    click Index "https://github.com/filipholik/smartgridsim/blob/main//GUI/PHPserver/style.css"
    click TopPHP "https://github.com/filipholik/smartgridsim/blob/main//GUI/PHPserver/topology/topology.php"
    click TopJS "https://github.com/filipholik/smartgridsim/blob/main//GUI/PHPserver/topology/topology.js"
    click TopStyle "https://github.com/filipholik/smartgridsim/blob/main//GUI/PHPserver/topology/style.css"
    click TopData "https://github.com/filipholik/smartgridsim/blob/main//GUI/PHPserver/topology/data.json"
    click Connect1 "https://github.com/filipholik/smartgridsim/blob/main//GUI/PHPserver/topology/connect_DSS1.sh"
    click Connect2 "https://github.com/filipholik/smartgridsim/blob/main//GUI/PHPserver/topology/connect_DSS2.sh"
    click Disc1 "https://github.com/filipholik/smartgridsim/blob/main//GUI/PHPserver/topology/disconnect_DSS1.sh"
    click Disc2 "https://github.com/filipholik/smartgridsim/blob/main//GUI/PHPserver/topology/disconnect_DSS2.sh"
    click Icons "https://github.com/filipholik/smartgridsim/tree/main//GUI/PHPserver/topology/icon/"
    click AdminPHP "https://github.com/filipholik/smartgridsim/blob/main//GUI/PHPserver/adminPanel/adminpanel.php"
    click AdminJS "https://github.com/filipholik/smartgridsim/blob/main//GUI/PHPserver/adminPanel/client.js"
    click Conn "https://github.com/filipholik/smartgridsim/blob/main//GUI/PHPserver/dbHandler/connectDb.php"
    click DSS1Val "https://github.com/filipholik/smartgridsim/blob/main//GUI/PHPserver/dbHandler/DSS1sensorValue.php"
    click DSS1Time "https://github.com/filipholik/smartgridsim/blob/main//GUI/PHPserver/dbHandler/DSS1sensorTimestamp.php"
    click DSS2Val "https://github.com/filipholik/smartgridsim/blob/main//GUI/PHPserver/dbHandler/DSS2sensorValue.php"
    click DSS2Time "https://github.com/filipholik/smartgridsim/blob/main//GUI/PHPserver/dbHandler/DSS2sensorTimestamp.php"
    click IED1GVal "https://github.com/filipholik/smartgridsim/blob/main//GUI/PHPserver/dbHandler/IED1gooseValue.php"
    click IED1GState "https://github.com/filipholik/smartgridsim/blob/main//GUI/PHPserver/dbHandler/IED1gooseState.php"
    click IED2SV "https://github.com/filipholik/smartgridsim/blob/main//GUI/PHPserver/dbHandler/IED2svValue.php"
    click IED3SVVal "https://github.com/filipholik/smartgridsim/blob/main//GUI/PHPserver/dbHandler/IED3svValue.php"
    click IED3SVState "https://github.com/filipholik/smartgridsim/blob/main//GUI/PHPserver/dbHandler/IED3svState.php"
    click IED4GVal "https://github.com/filipholik/smartgridsim/blob/main//GUI/PHPserver/dbHandler/IED4gooseValue.php"
    click IED4GState "https://github.com/filipholik/smartgridsim/blob/main//GUI/PHPserver/dbHandler/IED4gooseState.php"
    click GOOSETime "https://github.com/filipholik/smartgridsim/blob/main//GUI/PHPserver/dbHandler/GOOSETimestamp.php"
    click TimeStamp "https://github.com/filipholik/smartgridsim/blob/main//GUI/PHPserver/dbHandler/timestamp.php"
    click ASDU "https://github.com/filipholik/smartgridsim/blob/main//GUI/PHPserver/dbHandler/asdu.php"
    click State "https://github.com/filipholik/smartgridsim/blob/main//GUI/PHPserver/dbHandler/state.php"
    click PortConn "https://github.com/filipholik/smartgridsim/blob/main//GUI/PHPserver/dbHandler/portConnected.php"
    click DDOSMod "https://github.com/filipholik/smartgridsim/blob/main//GUI/PHPserver/dbHandler/DDOS.php"
    click GTK "https://github.com/filipholik/smartgridsim/blob/main//GUI/Application/GUI.c"

    %% Styles
    classDef orchestration stroke-dasharray: 5 5,stroke:#888,fill:#eee;
    classDef network fill:#c8e6c9,stroke:#2e7d32;
    classDef data fill:#bbdefb,stroke:#1565c0;
    classDef web fill:#ffe0b2,stroke:#ef6c00;
    classDef desktop fill:#e1bee7,stroke:#6a1b9a;
    classDef external fill:#f5f5f5,stroke:#9e9e9e;
```
