# hhhweihan/easytshark architecture

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

- Interactive diagram: https://gitdiagram.com/hhhweihan/easytshark
- Repository: https://github.com/hhhweihan/easytshark

## Overview

##### Project type and purpose
- EasyTshark is a standalone, command-line network packet capture and analysis tool (not a web app).
- It provides two modes:
- Real-time capture (from a network interface via tshark)
- Offline analysis (from an existing PCAP file)
- It stores packet metadata in a local SQLite database, performs XML/JSON conversions, and enriches data with IP geolocation via ip2region.

##### File structure
Top-level directories and files:
- run.sh, CMakeLists.txt → build & test orchestration
- / → headers for core modules and bundled third-party libs (loguru, rapidjson, rapidxml, ip2region)
- src/ → implementation of main, TsharkManager, utils, XDB search and benchmark
- output/ → compiled binaries (tshark_main, unit_tests)
- tests/ → Google Test suites
- data/ & logs/ → runtime outputs (packets.pcap, packets.db, packets.xml, packets.json, logs)

##### README for additional insights
- Dependencies: tshark, sqlite3, C++11, CMake
- Core features: dual capture modes, SQLite storage, XML ↔ JSON conversion, IP geolocation
- Testing: Google Test covers various modules (manager, utils, DB, conversion, error handling, integration)

##### Main components and their interactions
A. User CLI (Console)
- Presents mode selection menu (real-time vs offline)
- Collects parameters (interface name, duration, PCAP path)
→ invokes TsharkManager

B. TsharkManager
- Spawns tshark process (via ProcessUtil) → writes PCAP to working dir
- Parses PCAP metadata (tsharkDataType)
- Calls SQLiteUtil to create/open database and insert packet records
- Calls XMLConverter (rapidxml) to generate packets.xml
- Calls JSONConverter (rapidjson) to generate packets.json
- Calls IP2RegionUtil to enrich each packet’s IP

C. Storage Layer (SQLite)
- packets.db holds raw packet metadata for querying

D. Conversion Modules
- PCAP→XML (rapidxml)
- XML→JSON (rapidjson)

E. IP Geolocation
- ip2region.xdb lookup per IP address

F. Logging
- loguru records every operational step, errors, and performance metrics

G. Output files
- data/capture.pcap, packets.db, packets.xml, packets.json
- logs/…

H. Build & Test
- CMake & run.sh orchestrate compilation and Google Test execution
- Unit & integration tests ensure correctness of each module

##### Architectural patterns and principles
- Modular separation: manager, storage, conversion, util modules
- Single Responsibility: each converter and util has one domain
- Layered architecture: CLI → orchestration → processing → storage → output
- Dependency injection via headers and CMake targets

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Input/Output"
        CLI["CLI Interface"]:::io
    end

    subgraph "Core Processing"
        TsharkManager["TsharkManager"]:::core
        ProcessUtil["ProcessUtil / System Calls"]:::core
        DataModel["tsharkDataType"]:::core
        XMLConv["XMLConverter (rapidxml)"]:::core
        JSONConv["JSONConverter (rapidjson)"]:::core
        IP2RegionUtil["IP2RegionUtil"]:::core
        Logging["Logging (loguru)"]:::core
    end

    subgraph "Storage"
        SQLite["SQLiteUtil / packets.db"]:::storage
    end

    subgraph "External Dependencies"
        tshark["tshark CLI"]:::external
        sqlite3["SQLite3 Library"]:::external
        ip2region_db["ip2region.xdb"]:::external
        rapidxmlLib["rapidxml"]:::external
        rapidjsonLib["rapidjson"]:::external
        loguruLib["loguru"]:::external
    end

    subgraph "Output"
        outputs["Output Files\n(capture.pcap, packets.db,\npackets.xml, packets.json)"]:::io
        logsdir["Logs (logs/)"]:::io
    end

    subgraph "Build & Test"
        BuildTest["Build & Test Orchestration"]:::core
        Binaries["Binaries\n(tshark_main, unit_tests)"]:::io
        TestHarness["Test Harness"]:::testing
    end

    CLI -->|"invoke"| TsharkManager
    TsharkManager --> ProcessUtil
    ProcessUtil --> tshark
    tshark -->|"PCAP data"| ProcessUtil
    ProcessUtil -->|"PCAP file"| outputs
    TsharkManager --> DataModel
    DataModel --> SQLite
    SQLite --> sqlite3
    TsharkManager --> XMLConv
    XMLConv --> rapidxmlLib
    XMLConv --> JSONConv
    JSONConv --> rapidjsonLib
    JSONConv --> outputs
    TsharkManager --> IP2RegionUtil
    IP2RegionUtil --> ip2region_db
    TsharkManager --> Logging
    ProcessUtil --> Logging
    DataModel --> Logging
    XMLConv --> Logging
    JSONConv --> Logging
    IP2RegionUtil --> Logging
    Logging --> loguruLib
    BuildTest --> TsharkManager
    BuildTest --> ProcessUtil
    BuildTest --> DataModel
    BuildTest --> XMLConv
    BuildTest --> JSONConv
    BuildTest --> IP2RegionUtil
    BuildTest --> Logging
    BuildTest --> Binaries
    TestHarness --> TsharkManager
    TestHarness --> ProcessUtil
    TestHarness --> DataModel
    TestHarness --> XMLConv
    TestHarness --> JSONConv
    TestHarness --> IP2RegionUtil
    TestHarness --> Logging

    click CLI "https://github.com/hhhweihan/easytshark/blob/main/src/main.cpp"
    click TsharkManager "https://github.com/hhhweihan/easytshark/blob/main/include/tsharkManager.hpp"
    click ProcessUtil "https://github.com/hhhweihan/easytshark/blob/main/include/utils.hpp"
    click DataModel "https://github.com/hhhweihan/easytshark/blob/main/include/tsharkDataType.hpp"
    click IP2RegionUtil "https://github.com/hhhweihan/easytshark/blob/main/include/ip2region/xdb_search.h"
    click Logging "https://github.com/hhhweihan/easytshark/blob/main/include/loguru.hpp"
    click XMLConv "https://github.com/hhhweihan/easytshark/tree/main/include/rapidxml/"
    click JSONConv "https://github.com/hhhweihan/easytshark/tree/main/include/rapidjson/"
    click BuildTest "https://github.com/hhhweihan/easytshark/blob/main/CMakeLists.txt"
    click Binaries "https://github.com/hhhweihan/easytshark/tree/main/output/tshark_main"
    click TestHarness "https://github.com/hhhweihan/easytshark/tree/main/tests/"

    classDef io fill:#9f6,stroke:#333,stroke-width:1px
    classDef core fill:#6cf,stroke:#333,stroke-width:1px
    classDef storage fill:#fc6,stroke:#333,stroke-width:1px
    classDef external fill:#c6f,stroke:#333,stroke-width:1px
    classDef testing fill:#ccc,stroke:#333,stroke-width:1px
```
