# tbarbette/fastclick architecture

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

- Interactive diagram: https://gitdiagram.com/tbarbette/fastclick
- Repository: https://github.com/tbarbette/fastclick

## Overview

##### Project Type and Purpose
– FastClick is a high-performance, modular packet-processing framework (an extended fork of the Click Modular Router).
– It is not a web or mobile app but a “full-stack” networking system: a core engine, a library of packet‐processing “elements,” pluggable I/O backends (DPDK, Netmap, user-level sockets, kernel modules), configuration scripts, and client apps/tools.

##### Key Architectural Areas from File Tree & README
- Core engine & library
– include/click/… and lib/… hold the core C++ classes: packets, schedulers, pipelines, thread vectors, annotations.
- Element repositories
– elements/{ethernet,ip,ip6,tcpudp,flow,analysis,…} each group one domain’s building blocks.
– OS‐specific elements in linuxmodule/, bsdmodule/, userlevel/, minios/, ns/, etc.
- I/O backends
– FromDPDKDevice/ToDPDKDevice (DPDK), FromNetmapDevice, FromSocket, kernel proxy elements, etc.
- Flow subsystem (MiddleClick)
– flow/* and ctx/* implement session/flow tracking on top of packets.
- Specialized subprojects
– RSS++ (auto‐core scaling), PacketMill (binary specialization), PacketMill/README.packetmill.md, DPDK glue, Netmap glue.
- Tools & apps
– tools/ contains command‐line helpers (click-build, pretty, flatten, combine, etc.).
– apps/ contains GUIs (ClickController, clicky) and sample clients.
- Configuration & examples
– conf/ contains hundreds of .click pipeline examples organized by use case (nat, vpn, grid, ids, etc.).
– mininet/ Vagrant+Python topologies.

1. User Interfaces
– CLI (fastclick binary), clicksh, click-controller GUI, clicky GUI
– Configuration files under conf/ and .click syntax
2. Core Engine & Scheduler
– Packet parser, dispatcher, thread‐vector scheduler, pipeline builder
3. Element Library (cluster by package)
– elements/{ethernet,ip,ip6,tcpudp,analysis,flow,ids,aqm,…}
– OS‐specific elements: linuxmodule/, bsdmodule/, userlevel/, minios/
4. Flow Management (MiddleClick)
– flow/* + ctx/* subsystems for keeping stateful flows/sessions
5. I/O Backends
– DPDK glue: FromDPDKDevice/ToDPDKDevice
– Netmap: FromNetmapDevice/ToNetmapDevice
– Raw sockets, kernel proxies (kernelmodule elements), userlevel socket element
6. Support Libraries
– lib/ (compiled core code), include/click/ (headers), dpdk_glue, netmap glue
7. External Dependencies
– DPDK, Netmap, Kernel modules, OS, libnuma, python (for scripts), Meson/Ninja
8. Utilities & Tools
– tools/click-* command-line utilities
– click-buildtool.in, click-compile.in, scripts in etc/

B. Relationships & Data Flows
– Configuration (.click) flows into the Core Engine
– Core Engine instantiates a linear pipeline of Elements
– At pipeline ends, I/O Backends talk to hardware or kernel (DPDK/Netmap → NIC)
– Flow subsystem hooks into Element pipeline to maintain state and perform classi­fication
– Scheduler dispatches in-kernel threads or user-level threads via thread vectors
– Tools & Apps invoke the Core Engine or drive pipelines via the CLI API

C. Architectural Patterns & Principles
– Modular Pipeline (Chain of Responsibility): each Element performs one task
– Plugin architecture: many categories of Elements discovered at build time
– Strategy pattern for I/O backends: abstract QueueDevice with multiple concrete subclasses
– Thread-vector scheduler: abstract thread management allowing user‐level or kernel threads
– Feature toggles at build time via configure flags (–enable-dpdk, –enable-flow, –disable-clone, etc.)

D. Key Technologies & Frameworks
– C++11 for core code
– DPDK (user‐level high-speed I/O)
– Netmap (alternative fast I/O)
– libnuma, python3, meson/ninja, autotools (configure, Makefile.in)
– Mininet/Vagrant for network emulation

##### Detail Requirements
– Annotate build-time options (–enable-flow, –enable-dpdk) near relevant modules
– Show how PacketMill specializes a pipeline into a standalone binary
– Include small callouts for RSS++ scaling integration at FromDPDKDevice

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interfaces & Configuration
    subgraph "User Interfaces & Configuration"
        CLI["CLI (fastclick, clicksh)"]:::ui
        Conf[".click pipelines"]:::ui
        ClickCU["ClickController GUI"]:::ui
        ClickY["clicky GUI"]:::ui
    end
    CLI -->|"reads"| Conf
    CLI -->|"invokes"| Parser
    ClickCU -->|"drives"| Parser
    ClickY -->|"drives"| Parser

    %% Core Engine & Scheduler
    subgraph "Core Engine & Scheduler"
        Parser["Packet Parser"]:::core
        Builder["Pipeline Builder"]:::core
        Scheduler["Thread-Vector Scheduler"]:::core
        Dispatcher["Dispatcher"]:::core
    end
    Parser -->|"builds"| Builder
    Builder -->|"configures"| Scheduler
    Scheduler --> Dispatcher

    %% Element Library
    subgraph "Element Library"
        subgraph "Standard Elements"
            Eth["Ethernet Elements"]:::elements
            IP["IP Elements"]:::elements
            IPv6["IPv6 Elements"]:::elements
            TCPUDP["TCP/UDP Elements"]:::elements
            Analysis["Analysis Elements"]:::elements
            AQM["AQM Elements"]:::elements
            IDS["IDS Elements"]:::elements
            Grid["Grid Elements"]:::elements
            Other["Other Elements"]:::elements
        end
        subgraph "OS-Specific Elements"
            LinuxMod["LinuxModule Elements"]:::elements
            BSDMod["BSDModule Elements"]:::elements
            UserLevelEL["User-Level Elements"]:::elements
            MiniOS["MiniOS Elements"]:::elements
            NS2["NS-2 Simulation Elements"]:::elements
        end
    end
    Builder -->|"assembles pipeline of"| Eth & IP & IPv6 & TCPUDP & Analysis & AQM & IDS & Grid & Other & LinuxMod & BSDMod & UserLevelEL & MiniOS & NS2
    Scheduler <-->|"schedules"| Eth & IP & TCPUDP & Analysis & AQM & LinuxMod & UserLevelEL

    %% Flow Management
    subgraph "Flow Management (MiddleClick)"
        FlowEls["Flow Elements"]:::elements
        Ctx["Context Framework"]:::elements
    end
    FlowEls & Ctx -->|"hooks into"| Builder
    include_flow["Flow Headers & Parsers"]:::support
    lib_flow["lib/flow.cc & lib/flowbuffer.cc"]:::support
    FlowEls --> include_flow
    FlowEls --> lib_flow

    %% I/O Backends & Glue
    subgraph "I/O Backends & Glue"
        DPDK_EL["FromDPDK/ToDPDK Elements"]:::io
        NetmapEL["FromNetmap/ToNetmap Elements"]:::io
        SocketEL["Raw Socket Elements"]:::io
        KernelProxy["Kernel Module Proxy Elements"]:::io
        DPDKGlue["DPDK Glue"]:::support
        NetmapGlue["Netmap Glue"]:::support
    end
    Eth -->|"output to"| DPDK_EL & NetmapEL & SocketEL & KernelProxy
    TCPUDP -->|"output to"| DPDK_EL & NetmapEL
    DPDK_EL --> DPDKGlue
    NetmapEL --> NetmapGlue
    KernelProxy -->|"to NIC via kernel"| Kernel
    DPDK_EL -->|"--enable-dpdk"| DPDK
    NetmapEL -->|"--enable-netmap"| Netmap

    %% PacketMill Specializer
    PacketMill["PacketMill Specializer"]:::support
    Builder -->|"specializes pipeline"| PacketMill

    %% Support Libraries
    subgraph "Support Libraries"
        CoreLib["lib/ (core implementation)"]:::support
        IncAPI["include/click/ (headers)"]:::support
        AuxGlue["Auxiliary Glue Interfaces"]:::support
    end
    Parser & Scheduler & Builder --> CoreLib
    Parser & Scheduler --> IncAPI
    DPDKGlue & NetmapGlue --> AuxGlue

    %% Utilities & Tools
    subgraph "Utilities & Tools"
        Tools["tools/ (click-*, scripts)"]:::util
        Diagrams["etc/diagrams/"]:::util
        MininetTopo["mininet/ (Vagrant+Python)"]:::util
        BuildScripts["build scripts (configure, Makefile.in)"]:::util
    end
    Tools --> Parser
    Tools --> Builder

    %% External Dependencies
    subgraph "External Dependencies"
        DPDK["DPDK"]:::ext
        Netmap["Netmap"]:::ext
        Kernel["Kernel Modules"]:::ext
        OS["Operating System"]:::ext
        LibNUMA["libnuma"]:::ext
        Python3["Python3"]:::ext
        BuildSys["Meson/Ninja & Autotools"]:::ext
    end
    CoreLib & IncAPI --> OS & LibNUMA
    Diagrams & MininetTopo --> Python3
    BuildScripts --> BuildSys

    %% Click Events
    click CLI "https://github.com/tbarbette/fastclick/blob/main/userlevel/click.cc"
    click ClickCU "https://github.com/tbarbette/fastclick/tree/main/apps/ClickController/"
    click ClickY "https://github.com/tbarbette/fastclick/tree/main/apps/clicky/"
    click Conf "https://github.com/tbarbette/fastclick/tree/main/conf/"
    click IncAPI "https://github.com/tbarbette/fastclick/tree/main/include/click/"
    click CoreLib "https://github.com/tbarbette/fastclick/tree/main/lib/"
    click Eth "https://github.com/tbarbette/fastclick/tree/main/elements/ethernet/"
    click IP "https://github.com/tbarbette/fastclick/tree/main/elements/ip/"
    click IPv6 "https://github.com/tbarbette/fastclick/tree/main/elements/ip6/"
    click TCPUDP "https://github.com/tbarbette/fastclick/tree/main/elements/tcpudp/"
    click Analysis "https://github.com/tbarbette/fastclick/tree/main/elements/analysis/"
    click AQM "https://github.com/tbarbette/fastclick/tree/main/elements/aqm/"
    click IDS "https://github.com/tbarbette/fastclick/tree/main/elements/ids/"
    click Grid "https://github.com/tbarbette/fastclick/tree/main/elements/grid/"
    click LinuxMod "https://github.com/tbarbette/fastclick/tree/main/elements/linuxmodule/"
    click BSDMod "https://github.com/tbarbette/fastclick/tree/main/elements/bsdmodule/"
    click UserLevelEL "https://github.com/tbarbette/fastclick/tree/main/elements/userlevel/"
    click MiniOS "https://github.com/tbarbette/fastclick/tree/main/elements/minios/"
    click NS2 "https://github.com/tbarbette/fastclick/tree/main/elements/ns/"
    click FlowEls "https://github.com/tbarbette/fastclick/tree/main/elements/flow/"
    click Ctx "https://github.com/tbarbette/fastclick/tree/main/elements/ctx/"
    click include_flow "https://github.com/tbarbette/fastclick/tree/main/include/click/flow/"
    click lib_flow "https://github.com/tbarbette/fastclick/blob/main/lib/flow.cc"
    click DPDK_EL "https://github.com/tbarbette/fastclick/blob/main/elements/userlevel/fromdpdkdevice.cc"
    click NetmapEL "https://github.com/tbarbette/fastclick/blob/main/elements/userlevel/fromnetmapdevice.cc"
    click SocketEL "https://github.com/tbarbette/fastclick/blob/main/elements/userlevel/fromsocket.cc"
    click KernelProxy "https://github.com/tbarbette/fastclick/blob/main/elements/linuxmodule/fromdevice.cc"
    click DPDKGlue "https://github.com/tbarbette/fastclick/blob/main/include/click/dpdk_glue.hh"
    click NetmapGlue "https://github.com/tbarbette/fastclick/blob/main/include/click/netmapdevice.hh"
    click PacketMill "https://github.com/tbarbette/fastclick/blob/main/userlevel/packetmill.cc"
    click Tools "https://github.com/tbarbette/fastclick/tree/main/tools/"
    click Diagrams "https://github.com/tbarbette/fastclick/tree/main/etc/diagrams/"
    click MininetTopo "https://github.com/tbarbette/fastclick/tree/main/mininet/fastclick/"
    click BuildScripts "https://github.com/tbarbette/fastclick/tree/main/configure"
    
    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085;
    classDef core fill:#ffe5b4,stroke:#c46918;
    classDef elements fill:#d4edda,stroke:#155724;
    classDef io fill:#e2d6f3,stroke:#6f42c1;
    classDef support fill:#f8d7da,stroke:#721c24;
    classDef util fill:#fff3cd,stroke:#856404;
    classDef ext fill:#e2e3e5,stroke:#6c757d;
```
