# sammo3332/netzwerk-tool architecture

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

- Interactive diagram: https://gitdiagram.com/sammo3332/netzwerk-tool
- Repository: https://github.com/sammo3332/netzwerk-tool

## Overview

1. **Project shape**
   - This is a Python desktop application, not a web service.
   - The repo is split into a **backend analysis pipeline** and a **PyQt-based frontend GUI**, with a small entrypoint in `start.py`.

2. **Main user flow**
   - Users upload one or more network dataset files in the GUI.
   - The app runs analysis **asynchronously in the background**, then updates the interface with results.
   - Results can be inspected per graph or aggregated across a dataset.

3. **Frontend boundary**
   - `frontend/gui_main.py` is the GUI entrypoint.
   - `frontend/components/` contains the main UI building blocks: upload panel, toolbar, single-graph tab, dataset-analysis tab, analysis section, and visualization section.
   - `frontend/styles/default.css` provides the app’s look-and-feel.
   - The frontend is responsible for interaction, filtering controls, tab switching, and displaying tables/plots.

4. **Backend orchestration**
   - `backend/pipeline.py` appears to be the central coordinator that connects file ingestion, conversion, analysis, and result handling.
   - `backend/file_converter.py` and the files under `backend/converters/` handle format-specific parsing/conversion.
   - The backend is the main boundary between raw network files and normalized analysis-ready graph data.

5. **Format-specific ingestion**
   - The converter layer is organized by dataset family: `caida_converter.py`, `rocketfuel_converter.py`, and `sndlib_converter.py`.
   - The analyzer layer mirrors this structure with `caida_analysis.py`, `rocketfuel_analysis.py`, `sndlib_analysis.py`, and `topology_zoo_analysis.py`.
   - This suggests the app treats different source ecosystems separately rather than forcing one generic parser.

6. **Analysis subsystem**
   - `backend/analyzers/` is where graph metrics and dataset-level statistics are computed.
   - The README mentions metrics such as node count, edge count, density, centrality, connectivity, diameter, and efficiency.
   - This layer likely produces both per-graph summaries and collections used by the dataset-analysis tab.

7. **Data handling and persistence**
   - `backend/data_processing.py` likely normalizes, filters, or reshapes computed metrics before they reach the UI.
   - `backend/database_handler.py` suggests some kind of storage or cached result handling, even if the app is primarily file-driven.
   - `backend/utils.py` likely contains shared helpers used across conversion, analysis, and orchestration.

8. **Visualization path**
   - The README says graph visualization is based on **Matplotlib** and is intentionally static.
   - The frontend’s visualization section likely renders a selected graph after a row/file is opened from the analysis table.
   - The app avoids interactive graph libraries such as VisPy to keep dependencies simpler and improve compatibility.

9. **Two analysis views**
   - **Single Graph Analysis** focuses on individual uploaded files, with search, metric filtering, and direct opening of a graph visualization.
   - **Dataset Analysis** aggregates metrics across collections such as TopologyZoo or SNDlib and shows grouped charts.
   - This is an important architectural split: one path is per-file inspection, the other is cross-dataset comparison.

10. **Concurrency and responsiveness**
   - The GUI is designed to stay responsive while analysis runs in the background.
   - That means the backend work is likely executed off the main UI thread, with results pushed back into the interface when complete.
   - For an architecture diagram, this is a key runtime boundary between UI events and long-running analysis.

11. **Input formats and test data**
   - The tool is built around network graph files such as `.graphml`, `.xml`, `.txt`, and `.cch`.
   - `datasets-testen/` contains example inputs used for testing and demoing the app.
   - The repository also includes tests for data processing, file conversion, and GUI behavior, showing the three main seams of the system.

12. **External and non-core pieces**
   - `.github/workflows/main.yml` indicates CI automation, but it does not affect runtime architecture.
   - The GitHub feedback link and release packaging mentioned in the README are distribution/support elements, not core app components.
   - The core architecture remains: **file upload → conversion → analysis → result filtering/display → static graph visualization**.

Main entry points: [`backend/pipeline.py`](https://github.com/sammo3332/netzwerk-tool/blob/main/backend/pipeline.py) (Pipeline), [`frontend/gui_main.py`](https://github.com/sammo3332/netzwerk-tool/blob/main/frontend/gui_main.py) (GUI main), [`backend/file_converter.py`](https://github.com/sammo3332/netzwerk-tool/blob/main/backend/file_converter.py) (File converter), [`frontend/components/analysis_section.py`](https://github.com/sammo3332/netzwerk-tool/blob/main/frontend/components/analysis_section.py) (Analysis section)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry"]
  node_start_py["start.py<br/>entrypoint<br/>[start.py]"]
end

subgraph group_frontend["Frontend"]
  node_gui_main["GUI main<br/>PyQt app<br/>[gui_main.py]"]
  node_upload_panel["Upload panel<br/>ui component<br/>[upload_panel.py]"]
  node_toolbar["Toolbar<br/>ui component<br/>[toolbar.py]"]
  node_single_graph_tab["Single graph<br/>ui tab"]
  node_dataset_analysis_tab["Dataset analysis<br/>ui tab"]
  node_analysis_section["Analysis section<br/>ui component"]
  node_visualization_section["Visualization<br/>ui component"]
  node_default_css["Default style<br/>stylesheet<br/>[default.css]"]
end

subgraph group_backend["Backend"]
  node_pipeline["Pipeline<br/>orchestrator<br/>[pipeline.py]"]
  node_file_converter["File converter<br/>ingestion<br/>[file_converter.py]"]
  node_caida_converter["CAIDA conv.<br/>converter<br/>[caida_converter.py]"]
  node_rocketfuel_converter["Rocketfuel conv.<br/>converter"]
  node_sndlib_converter["SNDlib conv.<br/>converter"]
  node_caida_analysis["CAIDA analysis<br/>metrics<br/>[caida_analysis.py]"]
  node_rocketfuel_analysis["Rocketfuel analysis<br/>metrics"]
  node_sndlib_analysis["SNDlib analysis<br/>metrics<br/>[sndlib_analysis.py]"]
  node_topology_zoo_analysis["TopologyZoo analysis<br/>metrics"]
  node_data_processing["Data processing<br/>post-processing<br/>[data_processing.py]"]
  node_database_handler[("Result store<br/>storage/cache")]
  node_utils["Utils<br/>shared helpers<br/>[utils.py]"]
end

node_start_py -->|"launches"| node_gui_main
node_gui_main -->|"builds"| node_upload_panel
node_gui_main -->|"builds"| node_toolbar
node_gui_main -->|"hosts"| node_single_graph_tab
node_gui_main -->|"hosts"| node_dataset_analysis_tab
node_gui_main -->|"contains"| node_analysis_section
node_gui_main -->|"contains"| node_visualization_section
node_gui_main -.->|"styles"| node_default_css
node_upload_panel -->|"submits files"| node_pipeline
node_single_graph_tab -->|"drives"| node_analysis_section
node_single_graph_tab -->|"opens graph"| node_visualization_section
node_dataset_analysis_tab -->|"drives"| node_analysis_section
node_pipeline -->|"ingests"| node_file_converter
node_file_converter -->|"dispatches"| node_caida_converter
node_file_converter -->|"dispatches"| node_rocketfuel_converter
node_file_converter -->|"dispatches"| node_sndlib_converter
node_pipeline -->|"analyzes"| node_caida_analysis
node_pipeline -->|"analyzes"| node_rocketfuel_analysis
node_pipeline -->|"analyzes"| node_sndlib_analysis
node_pipeline -->|"analyzes"| node_topology_zoo_analysis
node_pipeline -->|"normalizes"| node_data_processing
node_data_processing -->|"stores"| node_database_handler
node_pipeline -.->|"uses"| node_utils
node_analysis_section -->|"consumes"| node_data_processing
node_visualization_section -.->|"requests data"| node_pipeline

click node_start_py "https://github.com/sammo3332/netzwerk-tool/blob/main/start.py"
click node_gui_main "https://github.com/sammo3332/netzwerk-tool/blob/main/frontend/gui_main.py"
click node_upload_panel "https://github.com/sammo3332/netzwerk-tool/blob/main/frontend/components/upload_panel.py"
click node_toolbar "https://github.com/sammo3332/netzwerk-tool/blob/main/frontend/components/toolbar.py"
click node_single_graph_tab "https://github.com/sammo3332/netzwerk-tool/blob/main/frontend/components/single_graph_tab.py"
click node_dataset_analysis_tab "https://github.com/sammo3332/netzwerk-tool/blob/main/frontend/components/dataset_analysis_tab.py"
click node_analysis_section "https://github.com/sammo3332/netzwerk-tool/blob/main/frontend/components/analysis_section.py"
click node_visualization_section "https://github.com/sammo3332/netzwerk-tool/blob/main/frontend/components/visualization_section.py"
click node_default_css "https://github.com/sammo3332/netzwerk-tool/blob/main/frontend/styles/default.css"
click node_pipeline "https://github.com/sammo3332/netzwerk-tool/blob/main/backend/pipeline.py"
click node_file_converter "https://github.com/sammo3332/netzwerk-tool/blob/main/backend/file_converter.py"
click node_caida_converter "https://github.com/sammo3332/netzwerk-tool/blob/main/backend/converters/caida_converter.py"
click node_rocketfuel_converter "https://github.com/sammo3332/netzwerk-tool/blob/main/backend/converters/rocketfuel_converter.py"
click node_sndlib_converter "https://github.com/sammo3332/netzwerk-tool/blob/main/backend/converters/sndlib_converter.py"
click node_caida_analysis "https://github.com/sammo3332/netzwerk-tool/blob/main/backend/analyzers/caida_analysis.py"
click node_rocketfuel_analysis "https://github.com/sammo3332/netzwerk-tool/blob/main/backend/analyzers/rocketfuel_analysis.py"
click node_sndlib_analysis "https://github.com/sammo3332/netzwerk-tool/blob/main/backend/analyzers/sndlib_analysis.py"
click node_topology_zoo_analysis "https://github.com/sammo3332/netzwerk-tool/blob/main/backend/analyzers/topology_zoo_analysis.py"
click node_data_processing "https://github.com/sammo3332/netzwerk-tool/blob/main/backend/data_processing.py"
click node_database_handler "https://github.com/sammo3332/netzwerk-tool/blob/main/backend/database_handler.py"
click node_utils "https://github.com/sammo3332/netzwerk-tool/blob/main/backend/utils.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_start_py toneBlue
class node_gui_main,node_upload_panel,node_toolbar,node_single_graph_tab,node_dataset_analysis_tab,node_analysis_section,node_visualization_section,node_default_css toneAmber
class node_pipeline,node_file_converter,node_caida_converter,node_rocketfuel_converter,node_sndlib_converter,node_caida_analysis,node_rocketfuel_analysis,node_sndlib_analysis,node_topology_zoo_analysis,node_data_processing,node_database_handler,node_utils toneMint
```

## Components

### Entry

Application startup

- [start.py](https://github.com/sammo3332/netzwerk-tool/blob/main/start.py): entrypoint · Launches the desktop app · `start.py`

### Frontend

PyQt GUI and display components

- [GUI main](https://github.com/sammo3332/netzwerk-tool/blob/main/frontend/gui_main.py): PyQt app · Main GUI entrypoint and window setup · `frontend/gui_main.py`
- [Upload panel](https://github.com/sammo3332/netzwerk-tool/blob/main/frontend/components/upload_panel.py): ui component · Handles dataset/file selection and upload flow · `frontend/components/upload_panel.py`
- [Toolbar](https://github.com/sammo3332/netzwerk-tool/blob/main/frontend/components/toolbar.py): ui component · Main actions and controls · `frontend/components/toolbar.py`
- [Single graph](https://github.com/sammo3332/netzwerk-tool/blob/main/frontend/components/single_graph_tab.py): ui tab · Per-file analysis and filtering view · `frontend/components/single_graph_tab.py`
- [Dataset analysis](https://github.com/sammo3332/netzwerk-tool/blob/main/frontend/components/dataset_analysis_tab.py): ui tab · Aggregated comparison view across datasets · `frontend/components/dataset_analysis_tab.py`
- [Analysis section](https://github.com/sammo3332/netzwerk-tool/blob/main/frontend/components/analysis_section.py): ui component · Tables, filters, and metric display · `frontend/components/analysis_section.py`
- [Visualization](https://github.com/sammo3332/netzwerk-tool/blob/main/frontend/components/visualization_section.py): ui component · Static Matplotlib graph rendering · `frontend/components/visualization_section.py`
- [Default style](https://github.com/sammo3332/netzwerk-tool/blob/main/frontend/styles/default.css): stylesheet · Shared frontend look and feel · `frontend/styles/default.css`

### Backend

Conversion, analysis, and result handling

- [Pipeline](https://github.com/sammo3332/netzwerk-tool/blob/main/backend/pipeline.py): orchestrator · Coordinates ingestion, conversion, analysis, and results · `backend/pipeline.py`
- [File converter](https://github.com/sammo3332/netzwerk-tool/blob/main/backend/file_converter.py): ingestion · Dispatches raw files into format-specific converters · `backend/file_converter.py`
- [CAIDA conv.](https://github.com/sammo3332/netzwerk-tool/blob/main/backend/converters/caida_converter.py): converter · Parses CAIDA-style inputs · `backend/converters/caida_converter.py`
- [Rocketfuel conv.](https://github.com/sammo3332/netzwerk-tool/blob/main/backend/converters/rocketfuel_converter.py): converter · Parses Rocketfuel-style inputs · `backend/converters/rocketfuel_converter.py`
- [SNDlib conv.](https://github.com/sammo3332/netzwerk-tool/blob/main/backend/converters/sndlib_converter.py): converter · Parses SNDlib-style inputs · `backend/converters/sndlib_converter.py`
- [CAIDA analysis](https://github.com/sammo3332/netzwerk-tool/blob/main/backend/analyzers/caida_analysis.py): metrics · Computes graph metrics for CAIDA datasets · `backend/analyzers/caida_analysis.py`
- [Rocketfuel analysis](https://github.com/sammo3332/netzwerk-tool/blob/main/backend/analyzers/rocketfuel_analysis.py): metrics · Computes graph metrics for Rocketfuel datasets · `backend/analyzers/rocketfuel_analysis.py`
- [SNDlib analysis](https://github.com/sammo3332/netzwerk-tool/blob/main/backend/analyzers/sndlib_analysis.py): metrics · Computes graph metrics for SNDlib datasets · `backend/analyzers/sndlib_analysis.py`
- [TopologyZoo analysis](https://github.com/sammo3332/netzwerk-tool/blob/main/backend/analyzers/topology_zoo_analysis.py): metrics · Computes graph metrics for TopologyZoo datasets · `backend/analyzers/topology_zoo_analysis.py`
- [Data processing](https://github.com/sammo3332/netzwerk-tool/blob/main/backend/data_processing.py): post-processing · Normalizes and reshapes computed results for display · `backend/data_processing.py`
- [Result store](https://github.com/sammo3332/netzwerk-tool/blob/main/backend/database_handler.py): storage/cache · Handles persistence or cached analysis results · `backend/database_handler.py`
- [Utils](https://github.com/sammo3332/netzwerk-tool/blob/main/backend/utils.py): shared helpers · Cross-cutting helper functions used by backend modules · `backend/utils.py`

## Connections

- start.py → GUI main: launches · Starts the GUI application
- GUI main → Upload panel: builds · Composes upload controls
- GUI main → Toolbar: builds · Composes toolbar controls
- GUI main → Single graph: hosts · Shows per-graph analysis workflow
- GUI main → Dataset analysis: hosts · Shows dataset aggregation workflow
- GUI main → Analysis section: contains · Renders metrics and filtering UI
- GUI main → Visualization: contains · Renders static graph visuals
- GUI main → Default style: styles · Applies shared UI styling
- Upload panel → Pipeline: submits files · Hands uploaded datasets to backend analysis
- Single graph → Analysis section: drives · Uses analysis controls for single-file inspection
- Single graph → Visualization: opens graph · Shows the selected graph visualization
- Dataset analysis → Analysis section: drives · Uses analysis controls for grouped comparisons
- Pipeline → File converter: ingests · Routes raw files into conversion
- File converter → CAIDA conv.: dispatches · CAIDA family parsing
- File converter → Rocketfuel conv.: dispatches · Rocketfuel family parsing
- File converter → SNDlib conv.: dispatches · SNDlib family parsing
- Pipeline → CAIDA analysis: analyzes · Runs CAIDA metrics
- Pipeline → Rocketfuel analysis: analyzes · Runs Rocketfuel metrics
- Pipeline → SNDlib analysis: analyzes · Runs SNDlib metrics
- Pipeline → TopologyZoo analysis: analyzes · Runs TopologyZoo metrics
- Pipeline → Data processing: normalizes · Prepares analysis output for the UI
- Data processing → Result store: stores · Persists or retrieves processed results
- Pipeline → Utils: uses · Shares helper logic across backend stages
- Analysis section → Data processing: consumes · Displays normalized metrics and summaries
- Visualization → Pipeline: requests data · Loads graph data for rendering