# vaibhavhd/flowguard architecture

> Architecture diagram of the GitHub repository vaibhavhd/flowguard, 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/vaibhavhd/flowguard
- Repository: https://github.com/vaibhavhd/flowguard

## Overview

##### Project type and purpose
- Flowguard is a network‐security plugin for the OpenDaylight (ODL) SDN controller.
- It consists of multiple Maven subprojects (API, implementation, CLI, features, Karaf assembly, integration tests) that together provide:
- A YANG‐defined northbound API for firewall‐rule management and conflict detection.
- An implementation that uses MD‐SAL (Model-Driven Service Abstraction Layer) to observe and resolve flow conflicts in OpenFlow switches.
- A CLI and REST interfaces for rule insertion and control operations.
- A visualizer bundle for DLUX (Web UI) to display topologies, flows, and conflicts.

##### File structure and map to high‐level components
- code/api → YANG models (flowguard.yang) + generated API stubs.
- code/impl → Java implementation:
- Registry data‐change listeners and callbacks
- Packet parsing and header‐space analysis
- Core engine (FlowguardImpl, FlowguardProvider)
- code/cli → Blueprint‐driven CLI bundle: RPC wiring, command definitions.
- code/features → Feature descriptors (features.xml) grouping API, impl, CLI, REST, UI.
- code/karaf → Karaf assembly: container configuration, deployable bundles.
- code/it → Integration tests exercising RPCs and end‐to‐end behavior.
- External scripts & data (results/scripts, data/) drive Mininet, invoke REST RPCs, collect logs.

##### README for runtime architecture
- Flowguard deploys into an ODL Karaf container alongside other features (e.g., openflow‐visualizer).
- Northbound RESTCONF calls invoke YANG RPCs (add‐fwrule, get‐conflicts, flowguard‐control).
- MD‐SAL datastore notifications trigger Flowguard’s data‐change listeners.
- Southbound: Flowguard issues flow‐modifications via MD‐SAL to OpenFlow plugin to push OpenFlow rules.
- DLUX UI modules display topology and conflict visualization.

a. Main components
- External systems:
- Operator CLI / REST client (scripts, curl)
- Mininet network of Open vSwitch (OVS) switches & hosts
- DLUX Web UI (Topology, OfVisualizer)
- ODL Karaf container:
- flowguard‐api bundle (YANG models, generated Java)
- flowguard‐impl bundle (core engine, packet parsing, data listeners)
- flowguard‐cli bundle (commands + Blueprint wiring)
- flowguard‐rest/UI bundles (if present)
- MD‐SAL datastore
- OpenFlow southbound plugin
- Other features (e.g., openflow‐visualizer)
b. Relationships & data flows
1. Operator issues RESTCONF RPC to /restconf/operations/flowguard:add-fwrule
2. RESTCONF subsystem routes to flowguard-api (YANG) → flowguard-cli if CLI RPCs
3. flowguard-api invokes flowguard-impl provider via MD‐SAL RPC callback
4. flowguard-impl registers new firewall rule in its registry and writes to MD‐SAL operational datastore
5. DataChangeListener in flowguard-impl picks up changes → triggers conflict detection via header‐space analysis
6. flowguard-impl issues MD‐SAL write to send flow‐mods southbound to OpenFlow plugin
7. OpenFlow plugin sends OFPT_FLOW_MOD to switches
8. DLUX UI & ofvisualizer bundle subscribe to topology & flow tables → render topology + conflicts
9. Integration tests & scripts interact via RESTCONF & verify logs
c. Key architectural patterns
- Model-Driven Service Abstraction Layer (MD-SAL)
- YANG‐based RPC API → Java API (generated stubs) → Implementation (Blueprint wiring)
- Event-driven listeners (DataChangeListenerFuture)
- Modular OSGi bundles in Karaf
d. Technologies & frameworks
- Java 8, Maven, OSGi
- ODL MD-SAL, YANG, RESTCONF, Blueprint
- OpenFlow southbound plugin
- DLUX (Angular, web UI)
- Mininet for test network

##### Summary of essential elements
- Components: REST client, Karaf container (with API, impl, CLI, features), MD-SAL, OpenFlow southbound, Mininet network, DLUX UI
- Interactions: YANG RPC → MD-SAL writes/reads → conflict detection → flow‐mod southbound → switch installs
- Patterns: MD-SAL event bus, OSGi modularity, YANG‐driven API
- Technologies: Java/Maven, ODL controller, OpenFlow, Mininet, RESTCONF, Blueprint, DLUX

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Systems"
        REST["Operator CLI/REST client"]:::external
        Scripts["Test Scripts & Topology Definitions"]:::external
        IT["Integration Tests"]:::external
        Net["Mininet network (OVS switches & hosts)"]:::external
    end

    subgraph "ODL Karaf Container"
        subgraph "Flowguard Bundles"
            API["flowguard-api (YANG API)"]:::control
            CLI["flowguard-cli (CLI & RPC)"]:::control
            IMPL["flowguard-impl (Core engine)"]:::control
        end
        FEATURES["Features (features.xml)"]:::control
        KARAF["Karaf Assembly"]:::control
        PARENT["Parent POM"]:::control
        MD["MD-SAL Datastore"]:::control
        OFPLUGIN["OpenFlow Plugin"]:::data
        subgraph "UI Bundles"
            DLUX["DLUX Web UI & Visualizer"]:::ui
        end
    end

    subgraph "Network"
        NetSwitch["OVS Switches & Hosts"]:::data
    end

    REST -->|"RESTCONF RPC"| API
    Scripts -->|"invoke REST RPCs"| REST
    Scripts -->|"mininet automation"| Net
    IT -->|"execute RPC tests"| API
    API -->|"invoke RPC callback"| IMPL
    IMPL -->|"write rule"| MD
    MD -->|"DataChange notification"| IMPL
    IMPL -->|"OF_FLOW_MOD"| OFPLUGIN
    OFPLUGIN -->|"OFPT_FLOW_MOD"| NetSwitch
    NetSwitch -->|"Topology & flow updates"| MD
    MD -->|"subscribe"| DLUX

    click API "https://github.com/vaibhavhd/flowguard/blob/master/code/api/src/main/yang/flowguard.yang"
    click CLI "https://github.com/vaibhavhd/flowguard/blob/master/code/cli/src/main/java/org/opendaylight/flowguard/cli/api/FlowguardCliCommands.java"
    click IMPL "https://github.com/vaibhavhd/flowguard/blob/master/code/impl/src/main/java/org/opendaylight/flowguard/impl/FlowguardImpl.java"
    click FEATURES "https://github.com/vaibhavhd/flowguard/blob/master/code/features/src/main/features/features.xml"
    click KARAF "https://github.com/vaibhavhd/flowguard/blob/master/code/karaf/pom.xml"
    click PARENT "https://github.com/vaibhavhd/flowguard/blob/master/code/pom.xml"
    click IT "https://github.com/vaibhavhd/flowguard/blob/master/code/it/src/test/java/org/opendaylight/flowguard/it/FlowguardIT.java"
    click Scripts "https://github.com/vaibhavhd/flowguard/tree/master/results/scripts/"

    classDef controlPlane fill:#8fc1e3,stroke:#333,stroke-width:1px
    classDef dataPlane fill:#a8d08d,stroke:#333,stroke-width:1px
    classDef ui fill:#f4b183,stroke:#333,stroke-width:1px
    classDef external fill:#cccccc,stroke:#333,stroke-width:1px

    class API,CLI,IMPL,FEATURES,KARAF,PARENT,MD controlPlane
    class OFPLUGIN,NetSwitch dataPlane
    class DLUX ui
    class REST,Scripts,IT,Net external
```
