# datahop/kademlia-simulator architecture

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

- Interactive diagram: https://gitdiagram.com/datahop/kademlia-simulator
- Repository: https://github.com/datahop/kademlia-simulator

## Overview

##### Main Components
- Simulation Engine: This is the heart of the project and is based on PeerSim. It handles core simulation functions such as event scheduling, network node interactions, and protocol executions.
- Configuration Module: Contains multiple configuration files under simulator/config that define different simulation scenarios (e.g., various Kademlia and DAS protocol configurations, including malicious cases).
- Protocol Implementations: Under simulator/src/main/java/peersim:
– Core Simulation Classes from the PeerSim framework (such as Node, Network, Scheduler, etc.).
– Specialized Kademlia components (found in the peersim/kademlia package) and its extensions for DAS protocols. These include classes for protocol configuration, node management, routing tables, traffic generators, and operations (e.g., PutOperation, GetOperation).
– Additional simulation protocols and dynamics (for example, ‘cdsim’ for cyclic simulations, ‘edsim’ for event-driven simulations, and the ‘dynamics’ and ‘reports’ packages for network behaviors and output generation).
- Utility and Support Modules:
– Configuration management utilities (peersim/config) for processing simulation parameters.
– Graph operations and reporting (in packages such as peersim/graph and peersim/reports).
– Miscellaneous utilities (such as those in peersim/util and vector) providing statistical analysis, random distribution functions, etc.
- Visualization Component:
– The visualiser directory (with visualiser/app.py, index.py, and network_visualiser.py) works as a front-end visualization/log analysis tool that reads simulation log output (in visualiser/log_folder).

##### Relationships and Interactions
- The simulation is initiated by a shell script (simulator/run.sh) that ingests a configuration file (e.g., config/kademlia.cfg) and starts the simulation engine.
- The configuration module feeds parameters into the simulation engine (the PeerSim core) and its protocol instances.
- The protocol components (like Kademlia, DAS protocols) are plugged into the simulation framework. They interact with core modules (such as scheduling and node management) to emulate network behavior.
- Reporting and logging modules capture data as the simulation runs. This data is then consumed by the visualization component (the Python visualiser) for analysis and graphic representation.
- The various Java packages interconnect to allow operations and dynamic updates (for instance, the ‘dynamics’ subpackage influences how nodes or connections are modified at runtime).

##### Architectural Patterns and Design Principles
- Modular Design: The project is split into clearly separated concerns: configuration, simulation core (engine), protocol implementations, utilities, and visualization.
- Plugin / Extension Pattern: The simulation protocols (especially in the peersim/kademlia directory) are designed to be interchangeable or extensible. New protocols or malicious scenarios can be integrated by simply adding new configuration or protocol files.
- Event-Driven Simulation: PeerSim’s architecture uses event scheduling and progression of simulation time (especially evident in the ‘edsim’ and ‘cdsim’ packages).

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Simulation Setup"
        RUN["Simulation Runner (run.sh)"]:::runner
        CFG["Configuration Module"]:::config
    end

    subgraph "Simulation Core"
        PS["PeerSim Simulation Engine"]:::engine
        CORE["Core Simulation & Event Scheduling"]:::core
    end

    subgraph "Protocol Layer"
        KP["Kademlia & DAS Protocols"]:::protocol
    end

    subgraph "Utilities & Visualization"
        UTIL["Utility & Support Modules"]:::util
        VIS["Visualization Component"]:::vis
    end

    RUN -->|"initiates"| PS
    CFG -->|"feeds_configuration"| PS
    PS -->|"schedules_events"| CORE
    PS -->|"runs_protocols"| KP
    KP -->|"integrates_with"| CORE
    PS -->|"logs_data"| UTIL
    UTIL -->|"supplies_metrics"| VIS

    click RUN "https://github.com/datahop/kademlia-simulator/blob/main/simulator/run.sh"
    click CFG "https://github.com/datahop/kademlia-simulator/tree/main/simulator/config"
    click PS "https://github.com/datahop/kademlia-simulator/blob/main/simulator/src/main/java/peersim/Simulator.java"
    click KP "https://github.com/datahop/kademlia-simulator/tree/main/simulator/src/main/java/peersim/kademlia"
    click CORE "https://github.com/datahop/kademlia-simulator/tree/main/simulator/src/main/java/peersim/core"
    click UTIL "https://github.com/datahop/kademlia-simulator/tree/main/simulator/src/main/java/peersim/util"
    click VIS "https://github.com/datahop/kademlia-simulator/blob/main/visualiser/app.py"

    classDef runner fill:#fff2cc,stroke:#d6b656,stroke-width:2px;
    classDef config fill:#fce5cd,stroke:#e69138,stroke-width:2px;
    classDef engine fill:#d9ead3,stroke:#6aa84f,stroke-width:2px;
    classDef core fill:#cfe2f3,stroke:#3c78d8,stroke-width:2px;
    classDef protocol fill:#d9d2e9,stroke:#8e7cc3,stroke-width:2px;
    classDef util fill:#ead1dc,stroke:#b854a1,stroke-width:2px;
    classDef vis fill:#f4cccc,stroke:#e06666,stroke-width:2px;
```
