# fdio/hicn architecture

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

- Interactive diagram: https://gitdiagram.com/fdio/hicn
- Repository: https://github.com/fdio/hicn

## Overview

##### Project type and purpose
- hICN is an open-source, modular network stack and toolset implementing Cisco’s hybrid Information-Centric Networking.
- It includes:
- A core “lib” library for low-level ICN packet and data structures.
- A transport library (“libtransport”) implementing reliable/unreliable delivery, congestion control, ARQ/FEC.
- A lightweight forwarder (“hicn-light”) for standalone ICN forwarding in IPv6.
- A VPP plugin (“hicn-plugin”) to integrate ICN forwarding into the VPP data plane.
- Control plane tools and libraries (“ctrl” and “libhicnctrl”) to configure faces, routes, policies.
- Example applications (“apps”) that consume the transport API (ping, http-proxy, higet, etc.).
- Telemetry collectors for metrics (collectd plugins, Kafka writers).
- A comprehensive test suite and Docker/CMake build infrastructure.

##### File structure and infer architecture
- Top-level modules map directly to architectural components: lib, libtransport, hicn-light, hicn-plugin, ctrl, apps, telemetry, tests.
- Each module is built via CMake; the plugin and forwarder implement the “forwarding plane,” libtransport is the “transport plane,” and lib is the “core plane.”
- The control plane sits beside the forwarder layer, talking to either hicn-light (via its API) or to VPP (via binary API through libhicnctrl).
- Apps sit “above” libtransport, consuming its socket-style API to produce/consume ICN traffic.

a. Core Library (“lib”)
b. Transport Library (“libtransport”)
c. Forwarding Plane
– hicn-light (standalone forwarder process)
– hicn-plugin (VPP plugin module loaded into VPP dataplane)
d. Control Plane
– libhicnctrl (C library to talk to forwarder or VPP)
– ctrl/facemgr (daemon or CLI tools to manage faces, routes)
e. Applications (“apps” folder)
– ping client/server, hyperf, http-proxy, higet, etc.
f. Telemetry
– collectd plugins, Kafka/influx writers, custom vpp-hicn collectors
g. Infrastructure & Tests
– Docker containers, functional tests, CMake build logic, packaging scripts

##### Relationships and data flows
- At runtime Applications → libtransport API → libtransport core → Forwarding Plane
- If using hicn-light: libtransport links to hicn-light’s UNIX/UDP connector.
- If using VPP: libtransport → memif or binary API → VPP dataplane with hicn-plugin.
- Control Plane tools → libhicnctrl → Forwarding Plane (either hicn-light’s API or VPP binary API)
- Telemetry collectors subscribe or poll metrics from the forwarder (via shared memory or plugin hooks) and forward to external systems (Kafka, InfluxDB).
- Tests and CI wrap and orchestrate containers running the full stack end-to-end.

##### Architectural patterns & design principles
- Clear separation of concerns: core, transport, forwarding, control, applications.
- Plugin‐based extensibility for the data plane (hicn-plugin in VPP).
- Layered socket‐style API for transport, enabling pluggable I/O modules (memif, UDP, TCP).
- CMake modular builds with packaging support for Ubuntu, Docker, macOS, Windows.
- Functional test harness orchestrating multiple nodes/containers.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Applications Layer
    subgraph "Applications"
        style Apps fill:#E8F4FC,stroke:#0288D1
        PingApp["ping"]:::app
        HigetApp["higet"]:::app
        HiperfApp["hiperf"]:::app
        HTTPProxyApp["http-proxy"]:::app
    end

    %% Transport Layer
    subgraph "Transport"
        style Transport fill:#F1F8E9,stroke:#689F38
        LibTransport["libtransport"]:::lib
    end

    %% Core Layer
    subgraph "Core"
        style Core fill:#FFF3E0,stroke:#EF6C00
        CoreLib["lib"]:::lib
    end

    %% Forwarding Plane
    subgraph "Forwarding Plane"
        style Forwarding fill:#FCE4EC,stroke:#D81B60
        HicnLight["hicn-light"]:::service
        subgraph "VPP Data Plane"
            style VPP fill:#F3E5F5,stroke:#8E24AA
            HicnPlugin["hicn-plugin"]:::service
        end
    end

    %% Control Plane
    subgraph "Control Plane"
        style Control fill:#E0F7FA,stroke:#006064
        LibHicnCtrl["libhicnctrl"]:::lib
        Facemgr["ctrl/facemgr"]:::service
    end

    %% Telemetry Layer
    subgraph "Telemetry"
        style Telemetry fill:#FFFDE7,stroke:#F9A825
        TL_Light["hicn-light-collectd"]:::telemetry
        TL_Kafka["kafka-collectd"]:::telemetry
        TL_VPP["vpp-collectd"]:::telemetry
    end

    %% Infrastructure & Tests
    subgraph "Infrastructure & Tests"
        style Infra fill:#ECEFF1,stroke:#455A64
        Tests["tests"]:::infra
        InfraScripts["CMakeLists.txt & cmake/ & scripts/"]:::infra
    end

    %% Data Flows
    PingApp -->|"uses API"| LibTransport
    HigetApp -->|"uses API"| LibTransport
    HiperfApp -->|"uses API"| LibTransport
    HTTPProxyApp -->|"uses API"| LibTransport

    LibTransport -->|"UNIX/UDP"| HicnLight
    LibTransport -->|"memif/binary API"| HicnPlugin

    Facemgr -->|"CLI/daemon"| LibHicnCtrl
    LibHicnCtrl -->|"API"| HicnLight
    LibHicnCtrl -->|"binary API"| HicnPlugin

    HicnLight -->|"metrics"| TL_Light
    HicnPlugin -->|"metrics"| TL_VPP
    TL_Light -->|"forward to Kafka"| TL_Kafka

    Tests -->|"orchestrates"| HicnLight
    Tests -->|"orchestrates"| HicnPlugin
    Tests -->|"orchestrates"| PingApp

    InfraScripts --> Tests

    CoreLib --> LibTransport

    %% Click Events
    click CoreLib "https://github.com/fdio/hicn/tree/master/lib/"
    click LibTransport "https://github.com/fdio/hicn/tree/master/libtransport/"
    click HicnLight "https://github.com/fdio/hicn/tree/master/hicn-light/"
    click HicnPlugin "https://github.com/fdio/hicn/tree/master/hicn-plugin/"
    click Facemgr "https://github.com/fdio/hicn/tree/master/ctrl/facemgr/"
    click LibHicnCtrl "https://github.com/fdio/hicn/tree/master/ctrl/libhicnctrl/"
    click PingApp "https://github.com/fdio/hicn/tree/master/apps/ping/"
    click HigetApp "https://github.com/fdio/hicn/tree/master/apps/higet/"
    click HiperfApp "https://github.com/fdio/hicn/tree/master/apps/hiperf/"
    click HTTPProxyApp "https://github.com/fdio/hicn/tree/master/apps/http-proxy/"
    click TL_Light "https://github.com/fdio/hicn/tree/master/telemetry/hicn-light-collectd/"
    click TL_Kafka "https://github.com/fdio/hicn/tree/master/telemetry/kafka-collectd/"
    click TL_VPP "https://github.com/fdio/hicn/tree/master/telemetry/vpp-collectd/"
    click Tests "https://github.com/fdio/hicn/tree/master/tests/"
    click InfraScripts "https://github.com/fdio/hicn/blob/master/CMakeLists.txt"

    %% Styles
    classDef lib fill:#FFF3E0,stroke:#EF6C00,font-weight:bold
    classDef service fill:#FCE4EC,stroke:#D81B60,font-weight:bold
    classDef app fill:#E8F4FC,stroke:#0288D1,font-weight:bold
    classDef telemetry fill:#FFFDE7,stroke:#F9A825,font-weight:bold
    classDef infra fill:#ECEFF1,stroke:#455A64,font-weight:bold
```
