# 0xbad4/lynx architecture

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

- Interactive diagram: https://gitdiagram.com/0xbad4/lynx
- Repository: https://github.com/0xbad4/lynx

## Overview

lynx is a header-only C++ library for inspecting, parsing, and processing packet data—not a general networking stack. Its principal workflow is to capture a Linux interface frame as Raw data, then use typed protocol accessors to interpret its layers. The graph also preserves packet construction/serialization primitives and the documented link-, internet-, and transport-layer protocol families. Several protocol headers were not sampled; their capabilities are documented, but uncertain internal dispatch relationships are omitted.

Main entry points: [`include/lynx/core/base/proto.h`](https://github.com/0xbad4/lynx/blob/main/include/lynx/core/base/proto.h) (Protocol base), [`include/lynx/net/platform/linux/iface.h`](https://github.com/0xbad4/lynx/blob/main/include/lynx/net/platform/linux/iface.h) (Interface capture), [`include/lynx/protocols/ll/eth`](https://github.com/0xbad4/lynx/tree/main/include/lynx/protocols/ll/eth) (Ethernet and VLAN), [`include/lynx/protocols/ll/frame.h`](https://github.com/0xbad4/lynx/blob/main/include/lynx/protocols/ll/frame.h) (Link frames)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Packet primitives"]
  node_objects["Base objects<br/>[obj.h]"]
  node_protocol_base["Protocol base<br/>[proto.h]"]
  node_buffer["Byte buffers<br/>[buffer.h]"]
  node_shared["Config and utilities"]
end

subgraph group_link["Link protocols"]
  node_raw["Raw payloads<br/>[raw.h]"]
  node_tlv["TLV structures<br/>[tlv.h]"]
  node_frames["Link frames<br/>[frame.h]"]
  node_ethernet["Ethernet and VLAN"]
  node_ppp["PPP family"]
  node_other_link["Other link protocols"]
end

subgraph group_network["Network protocols"]
  node_ip_packet["Internet packet base<br/>[packet.h]"]
  node_arp["ARP<br/>[arp.h]"]
  node_ipv4["IPv4<br/>[ipv4.h]"]
  node_ipv6["IPv6<br/>[ipv6.h]"]
  node_segment["Transport base<br/>[segment.h]"]
  node_transport["Transport protocols"]
end

subgraph group_linux["Linux networking"]
  node_iface["Interface capture<br/>[iface.h]"]
  node_socket["Raw socket helpers<br/>[socket.h]"]
  node_io["Networking API<br/>[io.h]"]
end

node_user(("Library user"))

node_user -->|"opens and reads"| node_iface
node_iface -->|"returns captured frame"| node_raw
node_user -->|"gets typed protocol"| node_ethernet
node_protocol_base -->|"inherits from"| node_objects
node_protocol_base -->|"serializes into"| node_buffer
node_objects -->|"uses config and errors"| node_shared
node_raw -->|"derives from"| node_protocol_base
node_tlv -->|"derives from"| node_protocol_base
node_frames -->|"derives from"| node_protocol_base
node_ethernet -->|"extends frame"| node_frames
node_ethernet -->|"extends Ethernet"| node_ethernet
node_ppp -->|"extends frame"| node_frames
node_other_link -->|"uses frame base"| node_frames
node_ip_packet -->|"derives from"| node_protocol_base
node_arp -->|"uses packet base"| node_ip_packet
node_ipv4 -->|"extends packet"| node_ip_packet
node_ipv6 -->|"extends packet"| node_ip_packet
node_segment -->|"derives from"| node_protocol_base
node_transport -->|"uses transport base"| node_segment
node_transport -->|"TCP uses packet type"| node_ipv4
node_transport -->|"TCP uses packet type"| node_ipv6
node_iface -->|"uses socket operations"| node_socket
node_iface -->|"dissects protocols"| node_raw
node_io -->|"exposes interface API"| node_iface
node_io -->|"exposes socket API"| node_socket

click node_objects "https://github.com/0xbad4/lynx/blob/main/include/lynx/core/base/obj.h"
click node_protocol_base "https://github.com/0xbad4/lynx/blob/main/include/lynx/core/base/proto.h"
click node_buffer "https://github.com/0xbad4/lynx/blob/main/include/lynx/core/buffer.h"
click node_shared "https://github.com/0xbad4/lynx/tree/main/include/lynx/core"
click node_raw "https://github.com/0xbad4/lynx/blob/main/include/lynx/protocols/extras/raw.h"
click node_tlv "https://github.com/0xbad4/lynx/blob/main/include/lynx/protocols/extras/tlv.h"
click node_frames "https://github.com/0xbad4/lynx/blob/main/include/lynx/protocols/ll/frame.h"
click node_ethernet "https://github.com/0xbad4/lynx/tree/main/include/lynx/protocols/ll/eth"
click node_ppp "https://github.com/0xbad4/lynx/tree/main/include/lynx/protocols/ll/ppp"
click node_other_link "https://github.com/0xbad4/lynx/tree/main/include/lynx/protocols/ll"
click node_ip_packet "https://github.com/0xbad4/lynx/blob/main/include/lynx/protocols/il/packet.h"
click node_arp "https://github.com/0xbad4/lynx/blob/main/include/lynx/protocols/il/arp.h"
click node_ipv4 "https://github.com/0xbad4/lynx/blob/main/include/lynx/protocols/il/ipv4.h"
click node_ipv6 "https://github.com/0xbad4/lynx/blob/main/include/lynx/protocols/il/ipv6.h"
click node_segment "https://github.com/0xbad4/lynx/blob/main/include/lynx/protocols/tl/segment.h"
click node_transport "https://github.com/0xbad4/lynx/tree/main/include/lynx/protocols/tl"
click node_iface "https://github.com/0xbad4/lynx/blob/main/include/lynx/net/platform/linux/iface.h"
click node_socket "https://github.com/0xbad4/lynx/blob/main/include/lynx/net/platform/linux/socket.h"
click node_io "https://github.com/0xbad4/lynx/blob/main/include/lynx/net/io.h"

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_objects,node_protocol_base,node_buffer,node_shared,node_user toneBlue
class node_raw,node_tlv,node_frames,node_ethernet,node_ppp,node_other_link toneAmber
class node_ip_packet,node_arp,node_ipv4,node_ipv6,node_segment,node_transport toneMint
class node_iface,node_socket,node_io toneRose
```

## Components

### Packet primitives

- [Base objects](https://github.com/0xbad4/lynx/blob/main/include/lynx/core/base/obj.h): `include/lynx/core/base/obj.h`
- [Protocol base](https://github.com/0xbad4/lynx/blob/main/include/lynx/core/base/proto.h): `include/lynx/core/base/proto.h`
- [Byte buffers](https://github.com/0xbad4/lynx/blob/main/include/lynx/core/buffer.h): `include/lynx/core/buffer.h`
- [Config and utilities](https://github.com/0xbad4/lynx/tree/main/include/lynx/core): `include/lynx/core`

### Link protocols

- [Raw payloads](https://github.com/0xbad4/lynx/blob/main/include/lynx/protocols/extras/raw.h): `include/lynx/protocols/extras/raw.h`
- [TLV structures](https://github.com/0xbad4/lynx/blob/main/include/lynx/protocols/extras/tlv.h): `include/lynx/protocols/extras/tlv.h`
- [Link frames](https://github.com/0xbad4/lynx/blob/main/include/lynx/protocols/ll/frame.h): `include/lynx/protocols/ll/frame.h`
- [Ethernet and VLAN](https://github.com/0xbad4/lynx/tree/main/include/lynx/protocols/ll/eth): `include/lynx/protocols/ll/eth`
- [PPP family](https://github.com/0xbad4/lynx/tree/main/include/lynx/protocols/ll/ppp): `include/lynx/protocols/ll/ppp`
- [Other link protocols](https://github.com/0xbad4/lynx/tree/main/include/lynx/protocols/ll): `include/lynx/protocols/ll`

### Network protocols

- [Internet packet base](https://github.com/0xbad4/lynx/blob/main/include/lynx/protocols/il/packet.h): `include/lynx/protocols/il/packet.h`
- [ARP](https://github.com/0xbad4/lynx/blob/main/include/lynx/protocols/il/arp.h): `include/lynx/protocols/il/arp.h`
- [IPv4](https://github.com/0xbad4/lynx/blob/main/include/lynx/protocols/il/ipv4.h): `include/lynx/protocols/il/ipv4.h`
- [IPv6](https://github.com/0xbad4/lynx/blob/main/include/lynx/protocols/il/ipv6.h): `include/lynx/protocols/il/ipv6.h`
- [Transport base](https://github.com/0xbad4/lynx/blob/main/include/lynx/protocols/tl/segment.h): `include/lynx/protocols/tl/segment.h`
- [Transport protocols](https://github.com/0xbad4/lynx/tree/main/include/lynx/protocols/tl): `include/lynx/protocols/tl`

### Linux networking

- [Interface capture](https://github.com/0xbad4/lynx/blob/main/include/lynx/net/platform/linux/iface.h): `include/lynx/net/platform/linux/iface.h`
- [Raw socket helpers](https://github.com/0xbad4/lynx/blob/main/include/lynx/net/platform/linux/socket.h): `include/lynx/net/platform/linux/socket.h`
- [Networking API](https://github.com/0xbad4/lynx/blob/main/include/lynx/net/io.h): `include/lynx/net/io.h`

### Other components

- **Library user**

## Connections

- Library user → Interface capture: opens and reads
- Interface capture → Raw payloads: returns captured frame (evidence: `include/lynx/net/platform/linux/iface.h`)
- Library user → Ethernet and VLAN: gets typed protocol
- Protocol base → Base objects: inherits from (evidence: `include/lynx/core/base/proto.h`)
- Protocol base → Byte buffers: serializes into (evidence: `include/lynx/core/base/proto.h`)
- Base objects → Config and utilities: uses config and errors (evidence: `include/lynx/core/base/obj.h`)
- Raw payloads → Protocol base: derives from (evidence: `include/lynx/protocols/extras/raw.h`)
- TLV structures → Protocol base: derives from (evidence: `include/lynx/protocols/extras/tlv.h`)
- Link frames → Protocol base: derives from (evidence: `include/lynx/protocols/ll/frame.h`)
- Ethernet and VLAN → Link frames: extends frame (evidence: `include/lynx/protocols/ll/eth/eth.h`)
- Ethernet and VLAN → Ethernet and VLAN: extends Ethernet (evidence: `include/lynx/protocols/ll/eth/dot1q.h`)
- PPP family → Link frames: extends frame (evidence: `include/lynx/protocols/ll/ppp/ppp.h`)
- Other link protocols → Link frames: uses frame base (evidence: `include/lynx/protocols/ll/eap.h`)
- Internet packet base → Protocol base: derives from (evidence: `include/lynx/protocols/il/packet.h`)
- ARP → Internet packet base: uses packet base (evidence: `include/lynx/protocols/il/arp.h`)
- IPv4 → Internet packet base: extends packet (evidence: `include/lynx/protocols/il/ipv4.h`)
- IPv6 → Internet packet base: extends packet (evidence: `include/lynx/protocols/il/ipv6.h`)
- Transport base → Protocol base: derives from (evidence: `include/lynx/protocols/tl/segment.h`)
- Transport protocols → Transport base: uses transport base (evidence: `include/lynx/protocols/tl/tcp.h`)
- Transport protocols → IPv4: TCP uses packet type (evidence: `include/lynx/protocols/tl/tcp.h`)
- Transport protocols → IPv6: TCP uses packet type (evidence: `include/lynx/protocols/tl/tcp.h`)
- Interface capture → Raw socket helpers: uses socket operations (evidence: `include/lynx/net/platform/linux/iface.h`)
- Interface capture → Raw payloads: dissects protocols (evidence: `include/lynx/net/platform/linux/iface.h`)
- Networking API → Interface capture: exposes interface API (evidence: `include/lynx/net/io.h`)
- Networking API → Raw socket helpers: exposes socket API (evidence: `include/lynx/net/io.h`)
