# zingerlittlebee/netop architecture

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

- Interactive diagram: https://gitdiagram.com/zingerlittlebee/netop
- Repository: https://github.com/zingerlittlebee/netop

## Overview

##### Project Type & Purpose
- netop is a single‐binary, terminal-based CLI/TUI application for monitoring and filtering network traffic using BPF rules.
- Written in Rust, it captures packets via libpcap, applies filters, aggregates metrics, and renders a real-time text UI.
- It is packaged for direct Cargo install, Docker, Snap, NetBSD pkgsrc and AUR.

##### File Structure Analysis
Top-level artifacts:
– .github/workflows: CI pipelines for linting (clippy), building/publishing crates, building & pushing Docker images.
– deploy/Dockerfile: container spec.
– snap/snapcraft.yaml: Snap packaging.
– Cargo.toml & lock: crate metadata and dependencies.
– src/: four modules:
- main.rs – argument parsing & entry point
- app.rs – orchestrator (“glue” logic)
- runner.rs – packet capture, BPF filter management, metrics computation
- ui.rs – TUI rendering & user input handling
– snapshot/: demo assets (e.g. dashboard.gif)

##### README Insights
- Describes features (multi-rule switching, real-time rate, total traffic, minimal resource use)
- Gives build/install instructions for Docker, Cargo, NetBSD, Arch (AUR)
- No end-to-end network architecture; focus is internal modules.

##### Key System Components & Interactions
A. Entry Point (CLI Layer)
– Parses options (interface name, help, version) using clap or similar.
– Instantiates `App` with configuration.
B. App Orchestrator
– Spawns/coordinates two sub‐systems: Runner and UI.
– Mediates messages/commands between UI and Runner (e.g. new BPF rule, switch/delete rule, shutdown).
C. Runner (Engine Layer)
– Wraps libpcap for packet capture on specified network interface.
– Manages BPF filter compilation & rule set.
– Computes metrics: real-time packet rate, total bytes, top talkers.
– Publishes metric events (via channels) to App.
D. UI (Presentation Layer)
– Subscribes to metric events, renders dashboard (text graphs, tables).
– Emits user commands back to App.
E. External Dependencies & Packaging
– libpcap (system library)
– Docker & Docker Hub (container distribution)
– Snapcraft, pkgsrc, AUR (OS packaging)
– GitHub Actions (CI/CD pipelines)

##### Architectural Patterns & Principles
- Modular separation of concerns (CLI vs orchestration vs engine vs UI)
- MVC-like flow:
Model = packet data & metrics (Runner)
View = TUI rendering (UI)
Controller = App mediating input and engine
- Asynchronous event flow via Rust channels or async tasks
- Single process, no external microservices

##### Detail & Clarity
- Use arrowheads to show directionality.
- Related items (src modules) within a “netop binary” boundary.
- Major config/build files (.github, Dockerfile, snapcraft.yaml, Cargo.toml) are shown as external build/deploy dependencies.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "netop binary"
        direction TB
        Main["main.rs (CLI Layer)"]:::uiux
        App["app.rs (Controller)"]:::core
        Runner["runner.rs (Packet capture & metrics)"]:::core
        UI["ui.rs (TUI & input)"]:::uiux
    end

    subgraph "External Runtime Dependencies"
        direction TB
        OSNIC["OS NIC"]:::external
        libpcap["libpcap"]:::external
    end

    subgraph "Packaging & Deployment"
        direction TB
        CI["GitHub Actions (CI/CD)"]:::external
        DockerPkg["deploy/Dockerfile"]:::external
        SnapPkg["snapcraft.yaml"]:::external
        CargoMeta["Cargo.toml & Cargo.lock"]:::external
        Demo["snapshot/ (demo assets)"]:::external
    end

    OSNIC -->|"packets"| libpcap
    libpcap -->|"captured packets"| Runner

    Main -->|"startup & config"| App
    App -->|"start capture & filter update"| Runner
    Runner -->|"metrics events"| App
    App -->|"render requests"| UI
    UI -->|"user commands"| App

    CI -.-> Main
    DockerPkg -.-> Main
    SnapPkg -.-> Main
    CargoMeta -.-> Main

    click Main "https://github.com/zingerlittlebee/netop/blob/main/src/main.rs"
    click App "https://github.com/zingerlittlebee/netop/blob/main/src/app.rs"
    click Runner "https://github.com/zingerlittlebee/netop/blob/main/src/runner.rs"
    click UI "https://github.com/zingerlittlebee/netop/blob/main/src/ui.rs"
    click libpcap "https://github.com/zingerlittlebee/netop/blob/main/Cargo.toml"
    click CI "https://github.com/zingerlittlebee/netop/blob/main/.github/workflows/*.yml"
    click DockerPkg "https://github.com/zingerlittlebee/netop/tree/main/deploy/Dockerfile"
    click SnapPkg "https://github.com/zingerlittlebee/netop/blob/main/snap/snapcraft.yaml"
    click CargoMeta "https://github.com/zingerlittlebee/netop/blob/main/Cargo.toml"
    click Demo "https://github.com/zingerlittlebee/netop/tree/main/snapshot/"

    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef uiux fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
