# al-shwaib/network-traffic-visualizer architecture

> Architecture diagram of the GitHub repository al-shwaib/network-traffic-visualizer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/al-shwaib/network-traffic-visualizer
- Repository: https://github.com/al-shwaib/network-traffic-visualizer

## Overview

##### Project Type and Purpose
- NetViz is a full-stack web application for real-time network traffic capture and 3D visualization.
- Backend: Python/Flask + Scapy for packet sniffing and stats.
- Frontend: HTML/CSS + Three.js (via network_visualizer.js) served by Flask.

##### File Structure
- src/main.py: Flask app entry point, orchestrates capture and serves endpoints.
- src/static:
- css/style.css – UI styling
- js/network_visualizer.js – client logic + Three.js visualization
- src/templates/index.html: single-page UI shell
- requirements.txt: Flask, Scapy, etc.
- No persistent database – state is in-memory/statistics computed on the fly.

##### Extract Key Architectural Insights from README
- Real-time packet capture (Scapy).
- Three visualization modes (Basic, Detailed, Summary).
- Live statistics dashboard (active nodes, data volume, rate).
- Interactive controls (rotate, filter).
- Full Arabic + English UI.

##### Main Components & Their Interactions
a. Packet Capture Service
- Component: Scapy Sniffer (embedded in main.py)
- Role: Captures live packets, extracts metadata (src/dest, size, protocol, timestamp, device type).
b. Business Logic & API Layer
- Component: Flask HTTP server
- Responsibilities:
- Expose REST/WebSocket endpoints for front-end data feed
- Aggregate stats (node count, data volume, rate)
- Serve static assets and index.html
c. Client-Side Visualization
- Component: network_visualizer.js + Three.js
- Responsibilities:
- To Flask endpoints (polling or WebSocket)
- Render 3D graph of network nodes & edges
- Switch between view modes, update stats dashboard
- Provide UI controls (rotate, filter, reset)
d. User’s Web Browser
- Entry point: http://localhost:5000
- Renders index.html, pulls in CSS & JS
e. External Dependencies
- Python libs: Flask, Scapy
- Three.js (bundled)

##### Architectural Patterns & Principles
- Single-Page Application pattern for front-end (static assets + client logic).
- Lightweight micro-service style: one Flask container handling both API and static content.
- Separation of concerns: capture → process → serve → render.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External & Network
    subgraph "External & Network"
        NET["Network Interface"]:::external
        DEPS["External Dependencies\n(Flask, Scapy, Three.js)"]:::external
    end

    %% Backend Services
    subgraph "Backend Services"
        SN["Scapy Sniffer"]:::backend
        API["Flask API & Static Server"]:::backend
    end

    %% Frontend/UI
    subgraph "Frontend/UI"
        BROWSER["User's Web Browser"]:::frontend
        INDEX["Single-Page UI Shell\n(index.html)"]:::frontend
        CSS["UI Styling\n(style.css)"]:::frontend
        JS["Client-Side Visualization\n(network_visualizer.js)"]:::frontend
    end

    %% Documentation
    subgraph "Documentation & Config"
        REQ["requirements.txt"]:::docs
        README["README.md"]:::docs
        LICENSE["LICENSE"]:::docs
    end

    %% Data Flows
    NET -->|"pcap packets"| SN
    DEPS --> SN
    SN -->|"parsed metadata JSON"| API
    API -->|"HTTP GET / (index.html)"| INDEX
    API -->|"HTTP GET /static/js/network_visualizer.js"| JS
    API -->|"HTTP GET /static/css/style.css"| CSS
    JS -->|"WebSocket/HTTP Polling JSON"| API
    JS -->|"render 3D graph (Three.js)"| BROWSER
    CSS -->|"apply styles"| BROWSER
    INDEX -->|"loads scripts & styles"| BROWSER

    %% Click Events
    click SN "https://github.com/al-shwaib/network-traffic-visualizer/blob/main/src/main.py"
    click API "https://github.com/al-shwaib/network-traffic-visualizer/blob/main/src/main.py"
    click JS "https://github.com/al-shwaib/network-traffic-visualizer/blob/main/src/static/js/network_visualizer.js"
    click CSS "https://github.com/al-shwaib/network-traffic-visualizer/blob/main/src/static/css/style.css"
    click INDEX "https://github.com/al-shwaib/network-traffic-visualizer/blob/main/src/templates/index.html"
    click REQ "https://github.com/al-shwaib/network-traffic-visualizer/blob/main/requirements.txt"
    click README "https://github.com/al-shwaib/network-traffic-visualizer/blob/main/README.md"
    click LICENSE "https://github.com/al-shwaib/network-traffic-visualizer/tree/main/LICENSE"

    %% Styles
    classDef external fill:#FFD580,stroke:#333,stroke-width:1px
    classDef backend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef frontend fill:#90EE90,stroke:#333,stroke-width:1px
    classDef docs fill:#F0E68C,stroke:#333,stroke-width:1px
```
