# google/gopacket architecture

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

- Interactive diagram: https://gitdiagram.com/google/gopacket
- Repository: https://github.com/google/gopacket

## Overview

##### Project type and purpose
- GoPacket is an open-source Go library (not a standalone application) designed to capture, parse, decode, and reassemble network packets at multiple layers.
- Its primary use case is to give Go developers a unified API to read packets from various sources (libpcap files, live captures, Linux AF_PACKET, BSD BPF, PF_RING), decode them into Go structs, reassemble streams, and feed the results into user code or higher-level tools.

##### File structure
- Top-level “capture” modules (each implementing a different packet source):
- pcap/ & pcapgo/ (libpcap‐based capture and pcap file read/write)
- afpacket/ (Linux AF_PACKET)
- bsdbpf/ (BSD BPF sniffer)
- pfring/ (PF_RING integration)
- Core decode pipeline files:
- packet.go, parser.go, decode.go – orchestrate reading raw bytes and invoking layer decoding
- layers/ – definitions of every protocol layer (Ethernet, IP, TCP, TLS, etc.) plus autogenerated enums and tests
- Stream reassembly modules:
- reassembly/ – generic TCP stream assembler, memory management
- tcpassembly/ – higher-level API to feed assembled streams to user callbacks
- defrag/ & ip4defrag/ – IP fragment reassembly utilities
- Utilities and examples:
- bytediff/, dumpcommand/, examples/, benchmark_test.go
- Build & CI config: .travis.*, go.mod, scripts, documentation stubs.

##### README for additional insights
- Confirms it’s a library for packet decoding.
- Points to godoc for API details.
- Notes Go version requirements.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Capture Backends"
        pcap["libpcap (C bindings)"]:::capture
        pcapgo["pcapgo (file I/O)"]:::capture
        afpacket["Linux AF_PACKET"]:::capture
        bsdbpf["BSD BPF Sniffer"]:::capture
        pfring["PF_RING Integration"]:::capture
    end

    subgraph "Decoding Pipeline"
        parser["Parser & Dispatcher"]:::decode
        decode["Raw Byte Orchestration"]:::decode
        layers_reg["Layer Registry & Decoders"]:::decode
        layertype["Layer Types"]:::decode
        layerclass["Layer Base"]:::decode
        layers_decoder["Decoder Entrypoint"]:::decode
    end

    subgraph "Packet Abstraction"
        packet["Packet Struct & Metadata"]:::decode
        flows["Flow Tracking & Metadata"]:::decode
    end

    subgraph "Stream Reassembly"
        defrag["IP Defragmenter"]:::reassembly
        ip4defrag["IPv4 Defragmenter"]:::reassembly
        reassembly_mod["TCP Assembler"]:::reassembly
        tcpassembly["TCP API (Callbacks)"]:::reassembly
    end

    subgraph "Utilities & Examples"
        bytediff["Byte Diff Tool"]:::utils
        dumpcommand["Dump Command"]:::utils
        examples["Examples & Demos"]:::utils
        benchmark["Benchmark Tests"]:::utils
        ci["Build & CI Config"]:::utils
        app["Application Callbacks"]:::utils
    end

    pcap --> parser
    pcapgo --> parser
    afpacket --> parser
    bsdbpf --> parser
    pfring --> parser

    parser --> decode
    decode --> layers_reg
    layertype --> layers_reg
    layerclass --> layers_reg
    layers_decoder --> layers_reg
    layers_reg --> packet
    packet --> defrag
    packet --> ip4defrag
    packet --> reassembly_mod
    packet --> app
    defrag --> parser
    ip4defrag --> parser
    reassembly_mod --> tcpassembly
    tcpassembly --> app

    click pcap "https://github.com/google/gopacket/tree/master/pcap/"
    click pcapgo "https://github.com/google/gopacket/tree/master/pcapgo/"
    click afpacket "https://github.com/google/gopacket/tree/master/afpacket/"
    click bsdbpf "https://github.com/google/gopacket/tree/master/bsdbpf/"
    click pfring "https://github.com/google/gopacket/tree/master/pfring/"
    click parser "https://github.com/google/gopacket/blob/master/parser.go"
    click decode "https://github.com/google/gopacket/blob/master/decode.go"
    click packet "https://github.com/google/gopacket/blob/master/packet.go"
    click layers_reg "https://github.com/google/gopacket/tree/master/layers/"
    click layertype "https://github.com/google/gopacket/blob/master/layertype.go"
    click layerclass "https://github.com/google/gopacket/blob/master/layerclass.go"
    click layers_decoder "https://github.com/google/gopacket/blob/master/layers_decoder.go"
    click reassembly_mod "https://github.com/google/gopacket/tree/master/reassembly/"
    click tcpassembly "https://github.com/google/gopacket/tree/master/tcpassembly/"
    click defrag "https://github.com/google/gopacket/tree/master/defrag/"
    click ip4defrag "https://github.com/google/gopacket/tree/master/ip4defrag/"
    click flows "https://github.com/google/gopacket/blob/master/flows.go"
    click bytediff "https://github.com/google/gopacket/tree/master/bytediff/"
    click dumpcommand "https://github.com/google/gopacket/tree/master/dumpcommand/"
    click examples "https://github.com/google/gopacket/tree/master/examples/"
    click benchmark "https://github.com/google/gopacket/blob/master/benchmark_test.go"
    click ci "https://github.com/google/gopacket/blob/master/go.mod"

    classDef capture fill:#cce5ff,stroke:#004085,color:#004085
    classDef decode fill:#d4edda,stroke:#155724,color:#155724
    classDef reassembly fill:#fff3cd,stroke:#856404,color:#856404
    classDef utils fill:#e2e3e5,stroke:#6c757d,color:#6c757d
```
