# nprint/nprintml architecture

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

- Interactive diagram: https://gitdiagram.com/nprint/nprintml
- Repository: https://github.com/nprint/nprintml

## Overview

1. nPrintML is a Python command-line package that orchestrates a packet-analysis pipeline rather than implementing the low-level network fingerprinting or ML algorithms itself. Its two main external engines are nPrint for feature generation and AutoGluon for model training.

2. The top-level entry points are `nprintml` / `nml`, implemented through `src/nprintml/cli.py` and `__main__.py`. `manage.py` is a separate developer/release entry point used for packaging and maintenance tasks, not for end-user analysis.

3. The core flow is: input PCAPs plus labels in → nPrint feature extraction → label aggregation/alignment → formatted feature datasets → AutoML training and evaluation. The repository is structured to keep these stages separable, which is important for diagramming the boundaries between data ingestion, preprocessing, and learning.

4. The `net` package is the integration boundary to nPrint itself. `net/install.py` bootstraps or installs the nPrint executable, while `net/execute.py` and `net/step.py` wrap invocation and pipeline-step behavior. In architecture terms, this is the “external process runner” layer that turns the repository into a usable workflow on a local machine or inside Docker.

5. The `label` package is responsible for turning raw labels into a form that matches the generated packet fingerprints. The presence of `aggregator/base.py`, `aggregator/pcap.py`, and `aggregator/index.py` suggests multiple label sources or grouping strategies, with the package acting as the label-normalization and alignment boundary.

6. The `learn` package is the training/prediction layer. `learn/automl.py` integrates AutoGluon, and `learn/step.py` likely provides pipeline-step orchestration around model fitting, validation, and inference. This layer consumes the feature datasets produced upstream and emits trained models and evaluation outputs downstream.

7. `pipeline.py` appears to be the composition point tying together the network, label, and learning stages. For an architecture diagram, this is the central workflow coordinator that routes inputs through the appropriate steps depending on whether the user is generating features, training, or running a partial pipeline.

8. The `util` package holds shared infrastructure used across stages: file-format handling, interface abstractions, I/O, and iteration helpers. `util/fileformat.py` is especially relevant because the test data shows support for multiple feature representations such as CSV gzip, Parquet, and `.fhr`, which means format conversion is an architectural concern rather than an implementation detail.

9. The repository is designed as a package under `src/`, with tests under `test/` exercising both the pipeline and CLI behavior. The `test/data` fixtures include paired PCAPs and labels, plus precomputed feature files, which indicates the intended integration points and expected intermediate artifacts.

10. Docker support is a first-class deployment path but remains an alternate execution environment. `image/Dockerfile` and the `nprintml-docker` wrapper script package the same CLI into a container, mainly to simplify setup and isolate dependencies such as nPrint and AutoGluon.

11. CI/CD is lightweight but relevant: GitHub Actions workflows cover test, benchmark, and release. That implies the repo treats reproducibility and command-line behavior as core qualities, with tests centered on end-to-end pipeline execution rather than just isolated library functions.

12. For an architecture diagram, the key boundaries are: user CLI, local orchestration code, external nPrint process, label ingestion/aggregation, dataset formatting, AutoGluon model training, and optional Docker packaging. The project is best understood as a workflow coordinator that glues together existing tools into a no-code traffic-analysis pipeline.

Main entry points: [`src/nprintml/pipeline.py`](https://github.com/nprint/nprintml/blob/main/src/nprintml/pipeline.py) (Pipeline), [`src/nprintml/util/fileformat.py`](https://github.com/nprint/nprintml/blob/main/src/nprintml/util/fileformat.py) (Formats), [`src/nprintml/learn/step.py`](https://github.com/nprint/nprintml/blob/main/src/nprintml/learn/step.py) (Learn step), [`src/nprintml/net/step.py`](https://github.com/nprint/nprintml/blob/main/src/nprintml/net/step.py) (Net step)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_src["Source"]
  node_src_nprintml_cli["CLI<br/>command entry<br/>[cli.py]"]
  node_src_nprintml_main["Module entry<br/>python entry<br/>[__main__.py]"]
  node_src_nprintml_pipeline{{"Pipeline<br/>workflow coordinator<br/>[pipeline.py]"}}
  node_src_nprintml_net_execute["Execute<br/>nPrint runner<br/>[execute.py]"]
  node_src_nprintml_net_install["Install nPrint<br/>bootstrap<br/>[install.py]"]
  node_src_nprintml_net_step["Net step<br/>pipeline step<br/>[step.py]"]
  node_src_nprintml_label_step["Label step<br/>pipeline step<br/>[step.py]"]
  node_src_nprintml_label_base["Label base<br/>label model<br/>[base.py]"]
  node_src_nprintml_label_pcap["PCAP labels<br/>label source<br/>[pcap.py]"]
  node_src_nprintml_label_index["Index labels<br/>label source<br/>[index.py]"]
  node_src_nprintml_learn_step["Learn step<br/>pipeline step<br/>[step.py]"]
  node_src_nprintml_learn_automl["AutoML<br/>AutoGluon bridge<br/>[automl.py]"]
  node_src_nprintml_fileformat["Formats<br/>data format<br/>[fileformat.py]"]
  node_src_nprintml_io["I/O<br/>shared utility<br/>[io.py]"]
  node_src_nprintml_interface["Interfaces<br/>shared utility<br/>[interface.py]"]
end

subgraph group_ops["Ops"]
  node_image_dockerfile["Dockerfile<br/>container build"]
  node_image_wrapper["Docker wrapper<br/>container entry"]
  node_manage_py["Manage<br/>maintenance entry<br/>[manage.py]"]
end

subgraph group_tests["Tests"]
  node_test_pipeline["Pipeline tests<br/>integration tests<br/>[test_pipeline.py]"]
  node_test_fileformat["Format tests<br/>integration tests<br/>[test_fileformat.py]"]
end

node_src_nprintml_main -->|"invokes"| node_src_nprintml_cli
node_src_nprintml_cli -->|"orchestrates"| node_src_nprintml_pipeline
node_src_nprintml_pipeline -->|"runs"| node_src_nprintml_net_step
node_src_nprintml_pipeline -->|"runs"| node_src_nprintml_label_step
node_src_nprintml_pipeline -->|"runs"| node_src_nprintml_learn_step
node_src_nprintml_net_step -->|"uses"| node_src_nprintml_net_execute
node_src_nprintml_net_step -->|"prepares"| node_src_nprintml_net_install
node_src_nprintml_net_execute -->|"emits"| node_src_nprintml_fileformat
node_src_nprintml_label_step -->|"builds on"| node_src_nprintml_label_base
node_src_nprintml_label_base -->|"specialized by"| node_src_nprintml_label_pcap
node_src_nprintml_label_base -->|"specialized by"| node_src_nprintml_label_index
node_src_nprintml_label_step -->|"aligns"| node_src_nprintml_fileformat
node_src_nprintml_learn_step -->|"delegates"| node_src_nprintml_learn_automl
node_src_nprintml_learn_step -->|"consumes"| node_src_nprintml_fileformat
node_src_nprintml_learn_step -->|"uses"| node_src_nprintml_interface
node_src_nprintml_io -->|"supports"| node_src_nprintml_fileformat
node_image_wrapper -->|"wraps"| node_src_nprintml_cli
node_image_dockerfile -->|"packages"| node_image_wrapper
node_manage_py -.->|"maintains"| node_src_nprintml_pipeline
node_test_pipeline -.->|"validates"| node_src_nprintml_pipeline
node_test_fileformat -.->|"validates"| node_src_nprintml_fileformat

click node_src_nprintml_cli "https://github.com/nprint/nprintml/blob/main/src/nprintml/cli.py"
click node_src_nprintml_main "https://github.com/nprint/nprintml/blob/main/src/nprintml/__main__.py"
click node_src_nprintml_pipeline "https://github.com/nprint/nprintml/blob/main/src/nprintml/pipeline.py"
click node_src_nprintml_net_execute "https://github.com/nprint/nprintml/blob/main/src/nprintml/net/execute.py"
click node_src_nprintml_net_install "https://github.com/nprint/nprintml/blob/main/src/nprintml/net/install.py"
click node_src_nprintml_net_step "https://github.com/nprint/nprintml/blob/main/src/nprintml/net/step.py"
click node_src_nprintml_label_step "https://github.com/nprint/nprintml/blob/main/src/nprintml/label/step.py"
click node_src_nprintml_label_base "https://github.com/nprint/nprintml/blob/main/src/nprintml/label/aggregator/base.py"
click node_src_nprintml_label_pcap "https://github.com/nprint/nprintml/blob/main/src/nprintml/label/aggregator/pcap.py"
click node_src_nprintml_label_index "https://github.com/nprint/nprintml/blob/main/src/nprintml/label/aggregator/index.py"
click node_src_nprintml_learn_step "https://github.com/nprint/nprintml/blob/main/src/nprintml/learn/step.py"
click node_src_nprintml_learn_automl "https://github.com/nprint/nprintml/blob/main/src/nprintml/learn/automl.py"
click node_src_nprintml_fileformat "https://github.com/nprint/nprintml/blob/main/src/nprintml/util/fileformat.py"
click node_src_nprintml_io "https://github.com/nprint/nprintml/blob/main/src/nprintml/util/io.py"
click node_src_nprintml_interface "https://github.com/nprint/nprintml/blob/main/src/nprintml/util/interface.py"
click node_image_dockerfile "https://github.com/nprint/nprintml/tree/main/image/Dockerfile"
click node_image_wrapper "https://github.com/nprint/nprintml/tree/main/image/nprintml-docker"
click node_manage_py "https://github.com/nprint/nprintml/blob/main/manage.py"
click node_test_pipeline "https://github.com/nprint/nprintml/blob/main/test/test_pipeline.py"
click node_test_fileformat "https://github.com/nprint/nprintml/blob/main/test/test_fileformat.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_src_nprintml_cli,node_src_nprintml_main,node_src_nprintml_pipeline,node_src_nprintml_net_execute,node_src_nprintml_net_install,node_src_nprintml_net_step,node_src_nprintml_label_step,node_src_nprintml_label_base,node_src_nprintml_label_pcap,node_src_nprintml_label_index,node_src_nprintml_learn_step,node_src_nprintml_learn_automl,node_src_nprintml_fileformat,node_src_nprintml_io,node_src_nprintml_interface toneBlue
class node_image_dockerfile,node_image_wrapper,node_manage_py toneAmber
class node_test_pipeline,node_test_fileformat toneMint
```

## Components

### Source

Primary package code under src/nprintml.

- [CLI](https://github.com/nprint/nprintml/blob/main/src/nprintml/cli.py): command entry · End-user command-line interface for nprintml/nml. · `src/nprintml/cli.py`
- [Module entry](https://github.com/nprint/nprintml/blob/main/src/nprintml/__main__.py): python entry · Python -m entrypoint for the package. · `src/nprintml/__main__.py`
- [Pipeline](https://github.com/nprint/nprintml/blob/main/src/nprintml/pipeline.py): workflow coordinator · Composes network, label, and learning stages into a runnable workflow. · `src/nprintml/pipeline.py`
- [Execute](https://github.com/nprint/nprintml/blob/main/src/nprintml/net/execute.py): nPrint runner · Wraps invocation of the external nPrint process. · `src/nprintml/net/execute.py`
- [Install nPrint](https://github.com/nprint/nprintml/blob/main/src/nprintml/net/install.py): bootstrap · Bootstraps or installs the nPrint executable. · `src/nprintml/net/install.py`
- [Net step](https://github.com/nprint/nprintml/blob/main/src/nprintml/net/step.py): pipeline step · Step orchestration around network feature generation. · `src/nprintml/net/step.py`
- [Label step](https://github.com/nprint/nprintml/blob/main/src/nprintml/label/step.py): pipeline step · Aligns and normalizes labels to generated fingerprints. · `src/nprintml/label/step.py`
- [Label base](https://github.com/nprint/nprintml/blob/main/src/nprintml/label/aggregator/base.py): label model · Shared aggregation and alignment abstractions for labels. · `src/nprintml/label/aggregator/base.py`
- [PCAP labels](https://github.com/nprint/nprintml/blob/main/src/nprintml/label/aggregator/pcap.py): label source · PCAP-oriented label aggregation strategy. · `src/nprintml/label/aggregator/pcap.py`
- [Index labels](https://github.com/nprint/nprintml/blob/main/src/nprintml/label/aggregator/index.py): label source · Index-based label aggregation strategy. · `src/nprintml/label/aggregator/index.py`
- [Learn step](https://github.com/nprint/nprintml/blob/main/src/nprintml/learn/step.py): pipeline step · Training and inference orchestration around the ML stage. · `src/nprintml/learn/step.py`
- [AutoML](https://github.com/nprint/nprintml/blob/main/src/nprintml/learn/automl.py): AutoGluon bridge · Integrates AutoGluon for model fitting and evaluation. · `src/nprintml/learn/automl.py`
- [Formats](https://github.com/nprint/nprintml/blob/main/src/nprintml/util/fileformat.py): data format · Handles feature dataset formats such as CSV gzip, Parquet, and FHR. · `src/nprintml/util/fileformat.py`
- [I/O](https://github.com/nprint/nprintml/blob/main/src/nprintml/util/io.py): shared utility · Shared file and filesystem helpers used across stages. · `src/nprintml/util/io.py`
- [Interfaces](https://github.com/nprint/nprintml/blob/main/src/nprintml/util/interface.py): shared utility · Common interfaces and abstractions for pipeline components. · `src/nprintml/util/interface.py`

### Ops

Packaging, container, and release entry points.

- [Dockerfile](https://github.com/nprint/nprintml/tree/main/image/Dockerfile): container build · Container image definition for packaged execution. · `image/Dockerfile`
- [Docker wrapper](https://github.com/nprint/nprintml/tree/main/image/nprintml-docker): container entry · Shell wrapper for running the packaged CLI in a container. · `image/nprintml-docker`
- [Manage](https://github.com/nprint/nprintml/blob/main/manage.py): maintenance entry · Developer/release entry point for packaging and maintenance tasks. · `manage.py`

### Tests

Integration and fixture-driven verification.

- [Pipeline tests](https://github.com/nprint/nprintml/blob/main/test/test_pipeline.py): integration tests · End-to-end pipeline behavior checks. · `test/test_pipeline.py`
- [Format tests](https://github.com/nprint/nprintml/blob/main/test/test_fileformat.py): integration tests · Verifies supported feature dataset formats. · `test/test_fileformat.py`

## Connections

- Module entry → CLI: invokes · Module entry delegates to the CLI.
- CLI → Pipeline: orchestrates · CLI routes user requests into the main workflow.
- Pipeline → Net step: runs · Pipeline starts with network feature generation.
- Pipeline → Label step: runs · Pipeline aligns labels with generated features.
- Pipeline → Learn step: runs · Pipeline trains or evaluates models downstream.
- Net step → Execute: uses · Network step invokes the nPrint runner.
- Net step → Install nPrint: prepares · Network stage can bootstrap the external dependency.
- Execute → Formats: emits · Execution produces feature datasets in supported formats.
- Label step → Label base: builds on · Label step uses common aggregation abstractions.
- Label base → PCAP labels: specialized by · PCAP label strategy implements the base boundary.
- Label base → Index labels: specialized by · Index label strategy implements the base boundary.
- Label step → Formats: aligns · Label processing depends on dataset format handling.
- Learn step → AutoML: delegates · Learning step hands off training to AutoML integration.
- Learn step → Formats: consumes · Learning consumes formatted feature datasets.
- Learn step → Interfaces: uses · Learning components share common interfaces.
- I/O → Formats: supports · I/O helpers underpin file and dataset handling.
- Docker wrapper → CLI: wraps · Container entry exposes the same user CLI.
- Dockerfile → Docker wrapper: packages · Dockerfile builds the runnable container image.
- Manage → Pipeline: maintains · Developer entry point supports packaging and maintenance workflows.
- Pipeline tests → Pipeline: validates · Tests exercise end-to-end orchestration.
- Format tests → Formats: validates · Tests cover supported file representations.