# ccie18643/pytcp architecture

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

- Interactive diagram: https://gitdiagram.com/ccie18643/pytcp
- Repository: https://github.com/ccie18643/pytcp

## Overview

##### Project type and purpose
- PyTCP is a user-space implementation of the full TCP/IP stack written in Python. It exports a sockets-like API (TcpIpStack) so external applications or examples can send/receive Ethernet, ARP, IP4/6, ICMP4/6, UDP, and TCP traffic via a Linux TAP interface.

##### File structure
- Top-level “examples” directory holds sample clients/services that import and drive the stack.
- Core library under “pytcp”:
- lib/ – packet, socket, IP/MAC address utilities and the stack manager
- protocols/ – per-protocol handlers, each split into Fast Packet Parser (fpa), Packet Stats (ps), Pre-header receive (phrx), Pre-header transmit (phtx), and fast packet parser parse (fpp) modules for ARP, Ether, IPv4, IPv6 (+ ext headers), ICMP4/6, UDP, TCP, RAW
- subsystems/ – concurrent components (rx_ring, tx_ring, packet_handler, timer, arp_cache, nd_cache, tracker)
- Configuration, build (Makefile), CI, and docs.

##### Inspect README insights
- The stack runs as multiple threads/subsystems, attaches to a TAP interface, auto-configures IPv4 via DHCP and IPv6 via SLAAC/DAD, and implements routing, fragmentation, reassembly, sliding window TCP with congestion control, ARP/ND caches, and socket APIs.

##### Main components
a. External user / example script (e.g., run_stack.py, tcp_echo_client.py)
b. TcpIpStack library (pytcp/__init__.py)
c. Subsystems threads:
- RxRing: reads raw Ethernet frames from TAP
- PacketHandler: dispatches frames through protocol stack
- Protocol handlers (Ethernet → ARP/IPv4/IPv6 → ICMP4/6, UDP, TCP)
- ARP cache & ND cache: address resolution and DAD
- Timer: manages retransmit, DAD, and other time-based events
- TxRing: queues assembled frames to TAP
d. Utility libraries: packet, logger, ip4_address, ip6_address, mac_address, socket API
e. Linux TAP interface & host network stack / bridge

##### Relationships & data-flow
- Inbound flow: TAP → RxRing → PacketHandler → protocol chain (Ether → IP4/6 → transport) → socket or example
- Outbound flow: application/socket → session manager → protocol phtx modules → PacketHandler → TxRing → TAP
- Timer triggers retransmit or DAD events, interacts with PacketHandler and protocol handlers.
- ARP/ND cache responds to address resolution requests and informs PacketHandler.

##### Architectural patterns & tech
- Thread-per-subsystem concurrency model
- Zero-copy packet parsing/assembly (FPA/FPP modules)
- Modular protocol layering (each protocol in its own package)
- BSD-sockets-style API overlay
- TAP device integration for user-space networking

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Examples
    subgraph "Examples" 
        direction TB
        RE[/"run_stack.py"/]:::external
        ICMPC[/"icmp_echo_client.py"/]:::external
        TCPC[/"tcp_echo_client.py"/]:::external
        UDPC[/"udp_echo_client.py"/]:::external
        TCPS[/"tcp_echo_service.py"/]:::external
        UDPS[/"udp_echo_service.py"/]:::external
    end

    %% Application API
    subgraph "Application/API Layer"
        direction TB
        SocketAPI(["Socket API"]):::util
    end

    %% Stack Manager
    subgraph "Core Library"
        direction TB
        Stack(["TcpIpStack"]):::backend
    end

    %% Utilities
    subgraph "Utilities" 
        direction TB
        Packet(["packet.py"]):::util
        PacketStats(["packet_stats.py"]):::util
        Logger(["logger.py"]):::util
        IP4Addr(["ip4_address.py"]):::util
        IP6Addr(["ip6_address.py"]):::util
        IPAddr(["ip_address.py"]):::util
        MACAddr(["mac_address.py"]):::util
        Tracker(["tracker.py"]):::util
        TXStatus(["tx_status.py"]):::util
        IPHelper(["ip_helper.py"]):::util
    end

    %% Subsystems
    subgraph "Subsystems (Threads)" 
        direction TB
        RxRing(["RxRing Thread"]):::backend
        PacketHandler(["PacketHandler Thread"]):::backend
        ARPCache(["ARP Cache Thread"]):::backend
        NDCache(["ND Cache Thread"]):::backend
        Timer(["Timer Thread"]):::backend
        TxRing(["TxRing Thread"]):::backend
    end

    %% Protocol Stack
    subgraph "Protocol Handlers" 
        direction TB
        Ether(["Ethernet"]):::backend
        ARP(["ARP"]):::backend
        IP4(["IPv4"]):::backend
        IP6(["IPv6"]):::backend
        IP6FRAG(["IPv6-Ext-Frag"]):::backend
        ICMP4(["ICMPv4"]):::backend
        ICMP6(["ICMPv6"]):::backend
        UDP(["UDP"]):::backend
        TCP(["TCP"]):::backend
        RAW(["RAW"]):::backend
        DHCP4(["DHCPv4 Client"]):::backend
    end

    %% External Host/TAP
    subgraph "External Network"
        direction TB
        TAP(["Linux TAP Interface"]):::external
        HostStack(["Host Network Stack"]):::external
    end

    %% Connections - Outbound
    RE -->|Application Data| SocketAPI
    ICMPC -->|Application Data| SocketAPI
    TCPC -->|Application Data| SocketAPI
    UDPC -->|Application Data| SocketAPI
    TCPS -->|Application Data| SocketAPI
    UDPS -->|Application Data| SocketAPI

    SocketAPI -->|"invoke API"| Stack
    Stack -->|calls phtx| UDP
    Stack -->|calls phtx| TCP
    Stack -->|calls phtx| RAW

    UDP -->|"phtx"| PacketHandler
    TCP -->|"phtx"| PacketHandler
    RAW -->|"phtx"| PacketHandler

    PacketHandler -->|"frame dispatch"| TxRing
    TxRing -->|"Ethernet frame"| TAP

    %% Connections - Inbound
    TAP -->|"Ethernet frame"| RxRing
    RxRing -->|"raw frame"| PacketHandler
    PacketHandler -->|"fpa"| Ether
    Ether -->|"pp to ARP/IP"| ARP
    Ether -->|"pp to IP4"| IP4
    Ether -->|"pp to IP6"| IP6

    IP4 -->|"to ICMP4/UDP/TCP/RAW"| ICMP4
    IP4 -->|...| UDP
    IP4 -->|...| TCP
    IP6 -->|"to ICMP6/UDP/TCP/RAW"| ICMP6
    IP6 -->|...| UDP
    IP6 -->|...| TCP

    ICMP4 -->|"to app"| SocketAPI
    ICMP6 -->|"to app"| SocketAPI
    UDP -->|"to app"| SocketAPI
    TCP -->|"to app"| SocketAPI
    RAW -->|"to app"| SocketAPI

    %% Timer and Caches
    Timer -->|"timeout events"| PacketHandler
    ARPCache -->|"resolve ARP"| PacketHandler
    NDCache -->|"resolve ND"| PacketHandler

    %% DHCP
    DHCP4 -->|"configure IP4"| Stack

    %% Host Integration
    HostStack --> TAP

    %% Click Events
    click RE "https://github.com/ccie18643/pytcp/blob/master/examples/run_stack.py"
    click ICMPC "https://github.com/ccie18643/pytcp/blob/master/examples/icmp_echo_client.py"
    click TCPC "https://github.com/ccie18643/pytcp/blob/master/examples/tcp_echo_client.py"
    click UDPC "https://github.com/ccie18643/pytcp/blob/master/examples/udp_echo_client.py"
    click TCPS "https://github.com/ccie18643/pytcp/blob/master/examples/tcp_echo_service.py"
    click UDPS "https://github.com/ccie18643/pytcp/blob/master/examples/udp_echo_service.py"
    click Stack "https://github.com/ccie18643/pytcp/blob/master/pytcp/__init__.py"
    click Stack "https://github.com/ccie18643/pytcp/blob/master/pytcp/lib/stack.py"
    click Packet "https://github.com/ccie18643/pytcp/blob/master/pytcp/lib/packet.py"
    click PacketStats "https://github.com/ccie18643/pytcp/blob/master/pytcp/lib/packet_stats.py"
    click Logger "https://github.com/ccie18643/pytcp/blob/master/pytcp/lib/logger.py"
    click IP4Addr "https://github.com/ccie18643/pytcp/blob/master/pytcp/lib/ip4_address.py"
    click IP6Addr "https://github.com/ccie18643/pytcp/blob/master/pytcp/lib/ip6_address.py"
    click IPAddr "https://github.com/ccie18643/pytcp/blob/master/pytcp/lib/ip_address.py"
    click MACAddr "https://github.com/ccie18643/pytcp/blob/master/pytcp/lib/mac_address.py"
    click Tracker "https://github.com/ccie18643/pytcp/blob/master/pytcp/lib/tracker.py"
    click TXStatus "https://github.com/ccie18643/pytcp/blob/master/pytcp/lib/tx_status.py"
    click IPHelper "https://github.com/ccie18643/pytcp/blob/master/pytcp/lib/ip_helper.py"
    click RxRing "https://github.com/ccie18643/pytcp/blob/master/pytcp/subsystems/rx_ring.py"
    click TxRing "https://github.com/ccie18643/pytcp/blob/master/pytcp/subsystems/tx_ring.py"
    click PacketHandler "https://github.com/ccie18643/pytcp/blob/master/pytcp/subsystems/packet_handler.py"
    click Timer "https://github.com/ccie18643/pytcp/blob/master/pytcp/subsystems/timer.py"
    click ARPCache "https://github.com/ccie18643/pytcp/blob/master/pytcp/subsystems/arp_cache.py"
    click NDCache "https://github.com/ccie18643/pytcp/blob/master/pytcp/subsystems/nd_cache.py"

    %% Styles
    classDef external fill:#d4f0d4,stroke:#333,stroke-width:1px
    classDef backend fill:#d0e1f9,stroke:#333,stroke-width:1px
    classDef util fill:#f9f0d0,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
