# kevincon/asio-rawsockets-example architecture

> Architecture diagram of the GitHub repository kevincon/asio-rawsockets-example, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kevincon/asio-rawsockets-example
- Repository: https://github.com/kevincon/asio-rawsockets-example

## Overview

##### Project Type and Purpose
- This is a small C++ command-line example (an open-source “demo tool”) illustrating how to send custom transport-layer (UDP) packets via Boost.Asio’s raw socket API.
- It is not a full-stack web app or microservice; instead, it’s a single binary that composes a packet header + payload and injects it into the kernel’s raw socket.

##### File Structure
- Top-level:
– CMakeLists.txt → build configuration
– src/ → C++ source files
- src/example.cpp → the main application logic (initializes header, builds packet, calls Boost.Asio)
- src/udp_header.hpp → encapsulates UDP header fields and (de)serialization
- src/raw.hpp → defines the “raw” protocol traits for Boost.Asio
- README.md → documents dependencies (CMake, Boost.System, Boost.Asio) and runtime steps

##### Key Insights from the README
- Uses Boost.Asio’s basic_raw_socket<asio::ip::raw> to send UDP-style packets.
- Requires root privileges to open a SOCK_RAW socket.
- Demonstrates layering: user-built UDP header + data → Asio streambuf → raw socket → kernel/network.
- Mentions Wireshark as an external observer.

##### Main Components
- Application Layer (“example” binary)
– Initializes io_service, constructs udp_header, writes header+payload into a streambuf.
- Networking Abstraction (Boost.Asio)
– basic_raw_socket<asio::ip::raw>
– asio::streambuf, io_service
- Protocol Helper Classes
– udp_header.hpp (holds source port, dest port, length, checksum)
– raw.hpp (protocol type/family traits)
- Operating System Kernel
– Receives the raw socket send request, hands off to network stack
– Applies IP header fields (checksum offload, protocol number)
- Network Interface / Loopback
– Delivers packet on 127.0.0.1 (or real NIC)
- External Observer
– Wireshark (sniffer) capturing and validating packet contents

##### Relationships and Data Flow
[example.cpp] → writes to → [Boost.Asio streambuf]
→ passes to → [basic_raw_socket]
→ invokes → [OS raw socket API]
→ pushes to → [Kernel network stack]
→ emits → [NIC / Loopback interface]
→ observed by → [Wireshark]

##### Architectural Patterns/Principles
- Layered networking stack (separation between application data, transport header, raw socket API, OS)
- Single responsibility: udp_header only handles header fields; raw.hpp only configures protocol traits
- Dependency injection: io_service passed into socket for event handling (though example is synchronous)

##### Technologies & Frameworks
- C++, Boost.Asio (basic_raw_socket, io_service, streambuf)
- CMake for build orchestration
- POSIX/WinSock raw socket API under the covers
- Wireshark as a monitoring tool (external)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Build & Docs"
        CMake["CMakeLists.txt"]:::config
        Readme["README.md"]:::doc
    end

    subgraph "Application Layer"
        Example["example.cpp"]:::app
        UdpHeader["udp_header.hpp"]:::app
        RawTraits["raw.hpp"]:::app
    end

    subgraph "Asio Library"
        IoService["asio::io_service"]:::lib
        Streambuf["asio::streambuf"]:::lib
        RawSocket["basic_raw_socket<asio.ip.raw>"]:::lib
    end

    subgraph "Operating System"
        OSApi["Kernel Raw Socket API"]:::os
        NetStack["Kernel Network Stack"]:::os
    end

    subgraph "Network"
        NIC["NIC / Loopback Interface"]:::network
    end

    Wireshark["Wireshark (Packet Sniffer)"]:::external

    CMake -->|"build config"| Example
    Readme -.->|"docs"| Example

    Example -->|"includes + init"| IoService
    Example -->|"constructs header"| UdpHeader
    Example -->|"uses traits"| RawTraits
    Example -->|"writes header+payload to"| Streambuf
    Streambuf -->|"passed to"| RawSocket
    RawSocket -->|".send_to(buffer, endpoint)"| OSApi
    OSApi -->|"hands off to"| NetStack
    NetStack -->|"emits packet to"| NIC
    NIC -->|"observed by"| Wireshark

    click Example "https://github.com/kevincon/asio-rawsockets-example/blob/master/src/example.cpp"
    click UdpHeader "https://github.com/kevincon/asio-rawsockets-example/blob/master/src/udp_header.hpp"
    click RawTraits "https://github.com/kevincon/asio-rawsockets-example/blob/master/src/raw.hpp"
    click CMake "https://github.com/kevincon/asio-rawsockets-example/blob/master/CMakeLists.txt"
    click Readme "https://github.com/kevincon/asio-rawsockets-example/blob/master/README.md"

    classDef app fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef lib fill:#d4edda,stroke:#333,stroke-width:1px
    classDef os fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef network fill:#f0e68c,stroke:#333,stroke-width:1px
    classDef external fill:#d6d8db,stroke:#333,stroke-width:1px
    classDef config fill:#e2e3e5,stroke:#333,stroke-width:1px
    classDef doc fill:#f8d7da,stroke:#333,stroke-width:1px
```
