# rdkcentral/networkmanager architecture

> Architecture diagram of the GitHub repository rdkcentral/networkmanager, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rdkcentral/networkmanager
- Repository: https://github.com/rdkcentral/networkmanager

## Overview

This repository implements a Thunder plugin that unifies network and WiFi management behind one API surface. The architectural center is a Thunder-hosted, out-of-process service that exposes both COMRPC and JSONRPC, then forwards those requests to one of two backend ecosystems selected at build time:

- GNOME NetworkManager
- RDK Network Service Manager

The plugin replaces the older separate Network and WiFiManager Thunder plugins that used IARM.

Main architectural layers

1. Public API and contract layer
- `definition/NetworkManager.json` is the Thunder JSON-RPC API definition.
- `interface/INetworkManager.h` is the C++ interface boundary used inside the plugin.
- `docs/NetworkManagerPlugin.md` documents the supported behavior.
- The `legacy/` folder contains the older Network and WiFiManager API surfaces kept for compatibility and regression coverage.

2. Thunder plugin host layer
- `plugin/Module.cpp` and `plugin/NetworkManager.cpp` are the Thunder plugin entry points.
- `plugin/NetworkManager.config` and `plugin/NetworkManager.conf.in` define plugin packaging and runtime registration.
- This layer is responsible for service lifecycle, registration with Thunder, and routing external method calls into the implementation.

3. Core orchestration layer
- `plugin/NetworkManagerImplementation.cpp/.h` contains the main business logic.
- `plugin/NetworkManagerJsonRpc.cpp` maps JSON-RPC requests into internal operations.
- `plugin/NetworkManagerConnectivity.cpp/.h`, `plugin/NetworkManagerStunClient.cpp/.h`, and `plugin/NetworkManagerTimer.h` handle connectivity state, reachability checks, STUN-based network discovery, and time-based retries/refreshes.
- `plugin/NetworkManagerSecretAgent.cpp/.h` handles credential/secret exchange with the backend network manager when WiFi authentication requires it.
- `plugin/NetworkManagerLogger.cpp/.h` centralizes logging.

4. Backend adapter layer
This is where the repo’s major architectural boundary lives: the same Thunder-facing API is adapted to different networking stacks.

GNOME path:
- `plugin/gnome/NetworkManagerGnome*` files implement GNOME-specific adapters, utilities, event handling, WiFi handling, and proxy logic.
- `plugin/gnome/gdbus/*` is the D-Bus/GDBus client and proxy layer used to communicate with GNOME NetworkManager.
- This path depends on GLib/libnm-style integration and GDBus-style IPC.

RDK path:
- `plugin/rdk/NetworkManagerRDKProxy.cpp/.h` is the adapter for RDK’s network service manager.

The compile-time selection is important: the plugin is designed so the Thunder API remains stable while the backend implementation changes underneath.

5. Legacy compatibility layer
- `legacy/LegacyNetworkAPIs.*` and `legacy/LegacyWiFiManagerAPIs.*` implement the older Thunder plugin behavior that interacted over IARM.
- These files represent the previous subsystem boundary and are kept to support existing consumers and test coverage during migration.

Core data flow

The main runtime flow is:

Thunder client
→ Thunder plugin entry point
→ JSONRPC/COMRPC handling
→ `NetworkManagerImplementation`
→ backend proxy/adaptor
→ D-Bus or backend-specific IPC
→ GNOME NetworkManager or RDK Network Service Manager
→ state/event callbacks back through the proxy
→ Thunder events/return values to the client

Connectivity-related behavior is a second flow:
- The plugin queries backend network state.
- It may use STUN and route/connectivity checks to determine external reachability, not just link status.
- Event handling propagates changes from the backend up to Thunder clients.

Secrets/WiFi authentication follow another flow:
- A backend request for credentials is handled by the secret-agent component.
- Credentials are fed back to the backend through the adapter layer.

Important boundaries

- Thunder boundary: everything external to the plugin enters through Thunder’s COMRPC/JSONRPC interfaces.
- IPC boundary: the plugin does not directly own the OS networking stack; it talks to an external service over D-Bus/GDBus or backend proxy interfaces.
- Backend abstraction boundary: GNOME and RDK implementations are separated so the same front-end API can work across platforms.
- Legacy boundary: the old IARM-based plugins are isolated from the new unified plugin, but their APIs and tests remain in-tree.

Supporting tools and services

- `tools/plugincli/` contains small CLI/test utilities for exercising the plugin interfaces.
- `tools/upnp/` contains router-discovery helpers and systemd units/scripts for UPnP-based discovery workflows.
- `conf/99-default-link-local` suggests default network configuration behavior used in packaging or deployment.
- `plugin/gnome/systemd/*` and `plugin/gnome/scripts/*` support operational setup and migration.

Testing architecture

The test layout reflects the architecture:

- `tests/l1Test/` covers lower-level components such as connectivity, route discovery, and STUN behavior.
- `tests/l2Test/` covers backend-specific and legacy-facing integration behavior:
  - `legacy/`
  - `libnm/`
  - `rdk/`
- `tests/mocks/` provides wrappers and mocks for external dependencies:
  - GLib
  - libnm
  - curl
  - IARM
  - Thunder framework types
  - legacy bus interfaces

That mock layer is important because it mirrors the repo’s real boundaries: the code is designed to isolate the plugin core from system libraries and IPC dependencies.

Build and integration model

- The project uses CMake throughout.
- `cmake/Find*.cmake` files indicate optional external dependencies such as IARM bus, T2, and rdklogger.
- The repo is built and validated via GitHub Actions workflows in `.github/workflows/`, including backend-specific tests and PR validation.

In diagram form, the most important thing to show is that this is not a simple monolith: it is a Thunder-facing orchestration layer sitting between a stable network-management API and two alternative backend IPC stacks, with additional subcomponents for connectivity assessment, secret handling, and legacy compatibility.

Main entry points: [`plugin/NetworkManagerImplementation.cpp`](https://github.com/rdkcentral/networkmanager/blob/HEAD/plugin/NetworkManagerImplementation.cpp) (Manager impl), [`plugin/gnome/NetworkManagerGnomeProxy.cpp`](https://github.com/rdkcentral/networkmanager/blob/HEAD/plugin/gnome/NetworkManagerGnomeProxy.cpp) (GNOME proxy), [`plugin/NetworkManagerConnectivity.cpp`](https://github.com/rdkcentral/networkmanager/blob/HEAD/plugin/NetworkManagerConnectivity.cpp) (Connectivity), [`tests/l2Test`](https://github.com/rdkcentral/networkmanager/tree/HEAD/tests/l2Test) (L2 tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "API & contract"
  definition_json["Network API<br/>jsonrpc contract"]
  interface_inm["INetworkManager<br/>cpp interface<br/>[INetworkManager.h]"]
  docs_plugin["Plugin docs<br/>documentation"]
end

subgraph "Thunder host"
  module_cpp["Module<br/>thunder entry<br/>[Module.cpp]"]
  plugin_cpp["Plugin host<br/>thunder plugin<br/>[NetworkManager.cpp]"]
end

subgraph "Core orchestration"
  impl_cpp["Manager impl<br/>orchestrator"]
  jsonrpc_cpp["JSON-RPC map<br/>rpc adapter"]
  connectivity_cpp["Connectivity<br/>state engine"]
  stun_cpp["STUN client<br/>network probe"]
  secret_agent_cpp["Secret agent<br/>credential bridge"]
  logger_cpp["Logger<br/>logging"]
end

subgraph "GNOME backend"
  gnome_proxy["GNOME proxy<br/>backend adapter"]
  gnome_wifi["GNOME WiFi<br/>backend wifi"]
  gnome_events["GNOME events<br/>event bridge"]
  gnome_gdbus_client["GDBus client<br/>ipc client"]
  gnome_gdbus_proxy["GDBus proxy<br/>ipc proxy"]
end

subgraph "RDK backend"
  rdk_proxy["RDK proxy<br/>backend adapter"]
end

subgraph "Legacy compatibility"
  legacy_network["Legacy network<br/>compat plugin"]
  legacy_wifi["Legacy WiFi<br/>compat plugin"]
end

subgraph "Support & tests"
  l1_tests["L1 tests<br/>unit tests"]
  l2_tests["L2 tests<br/>integration tests"]
  mocks["Mocks<br/>test doubles"]
  plugincli["Plugin CLI<br/>tooling"]
  upnp_tools["UPnP tools<br/>tooling"]
end

definition_json -->|"defines"| interface_inm
docs_plugin -->|"documents"| definition_json
module_cpp -->|"boots"| plugin_cpp
plugin_cpp -->|"creates"| impl_cpp
impl_cpp -->|"handles"| jsonrpc_cpp
jsonrpc_cpp -->|"targets"| interface_inm
impl_cpp -->|"uses"| connectivity_cpp
connectivity_cpp -->|"probes"| stun_cpp
impl_cpp -->|"delegates"| secret_agent_cpp
impl_cpp -->|"logs"| logger_cpp
impl_cpp -->|"selects"| gnome_proxy
impl_cpp -->|"selects"| rdk_proxy
gnome_proxy -->|"bridges"| gnome_gdbus_proxy
gnome_gdbus_proxy -->|"calls"| gnome_gdbus_client
gnome_gdbus_client -->|"receives"| gnome_events
gnome_proxy -->|"implements"| gnome_wifi
gnome_proxy -->|"requests secrets"| secret_agent_cpp
rdk_proxy -->|"reports state"| connectivity_cpp
legacy_network -->|"compat with"| plugin_cpp
legacy_wifi -->|"compat with"| plugin_cpp
l1_tests -->|"covers"| connectivity_cpp
l1_tests -->|"covers"| stun_cpp
l2_tests -->|"covers"| gnome_proxy
l2_tests -->|"covers"| rdk_proxy
l2_tests -->|"covers"| legacy_network
l2_tests -->|"covers"| legacy_wifi
mocks -->|"stubs"| gnome_gdbus_client
mocks -->|"stubs"| rdk_proxy
plugincli -->|"exercises"| gnome_proxy
upnp_tools -->|"supports"| connectivity_cpp

click definition_json "https://github.com/rdkcentral/networkmanager/blob/develop/definition/NetworkManager.json"
click interface_inm "https://github.com/rdkcentral/networkmanager/blob/develop/interface/INetworkManager.h"
click docs_plugin "https://github.com/rdkcentral/networkmanager/blob/develop/docs/NetworkManagerPlugin.md"
click module_cpp "https://github.com/rdkcentral/networkmanager/blob/develop/plugin/Module.cpp"
click plugin_cpp "https://github.com/rdkcentral/networkmanager/blob/develop/plugin/NetworkManager.cpp"
click impl_cpp "https://github.com/rdkcentral/networkmanager/blob/develop/plugin/NetworkManagerImplementation.cpp"
click jsonrpc_cpp "https://github.com/rdkcentral/networkmanager/blob/develop/plugin/NetworkManagerJsonRpc.cpp"
click connectivity_cpp "https://github.com/rdkcentral/networkmanager/blob/develop/plugin/NetworkManagerConnectivity.cpp"
click stun_cpp "https://github.com/rdkcentral/networkmanager/blob/develop/plugin/NetworkManagerStunClient.cpp"
click secret_agent_cpp "https://github.com/rdkcentral/networkmanager/blob/develop/plugin/NetworkManagerSecretAgent.cpp"
click logger_cpp "https://github.com/rdkcentral/networkmanager/blob/develop/plugin/NetworkManagerLogger.cpp"
click gnome_proxy "https://github.com/rdkcentral/networkmanager/blob/develop/plugin/gnome/NetworkManagerGnomeProxy.cpp"
click gnome_wifi "https://github.com/rdkcentral/networkmanager/blob/develop/plugin/gnome/NetworkManagerGnomeWIFI.cpp"
click gnome_events "https://github.com/rdkcentral/networkmanager/blob/develop/plugin/gnome/NetworkManagerGnomeEvents.cpp"
click gnome_gdbus_client "https://github.com/rdkcentral/networkmanager/blob/develop/plugin/gnome/gdbus/NetworkManagerGdbusClient.cpp"
click gnome_gdbus_proxy "https://github.com/rdkcentral/networkmanager/blob/develop/plugin/gnome/gdbus/NetworkManagerGdbusProxy.cpp"
click rdk_proxy "https://github.com/rdkcentral/networkmanager/blob/develop/plugin/rdk/NetworkManagerRDKProxy.cpp"
click legacy_network "https://github.com/rdkcentral/networkmanager/blob/develop/legacy/LegacyNetworkAPIs.cpp"
click legacy_wifi "https://github.com/rdkcentral/networkmanager/blob/develop/legacy/LegacyWiFiManagerAPIs.cpp"
click l1_tests "https://github.com/rdkcentral/networkmanager/tree/develop/tests/l1Test"
click l2_tests "https://github.com/rdkcentral/networkmanager/tree/develop/tests/l2Test"
click mocks "https://github.com/rdkcentral/networkmanager/tree/develop/tests/mocks"
click plugincli "https://github.com/rdkcentral/networkmanager/tree/develop/tools/plugincli"
click upnp_tools "https://github.com/rdkcentral/networkmanager/tree/develop/tools/upnp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class definition_json,interface_inm,docs_plugin,l1_tests,l2_tests,mocks,plugincli,upnp_tools toneBlue
class module_cpp,plugin_cpp toneAmber
class impl_cpp,jsonrpc_cpp,connectivity_cpp,stun_cpp,secret_agent_cpp,logger_cpp toneMint
class gnome_proxy,gnome_wifi,gnome_events,gnome_gdbus_client,gnome_gdbus_proxy toneRose
class rdk_proxy toneIndigo
class legacy_network,legacy_wifi toneTeal
```

## Components

### API & contract

Public surface, interface boundary, and documentation.

- [Network API](https://github.com/rdkcentral/networkmanager/blob/HEAD/definition/NetworkManager.json): jsonrpc contract · Thunder JSON-RPC definition for the unified network manager. · `definition/NetworkManager.json`
- [INetworkManager](https://github.com/rdkcentral/networkmanager/blob/HEAD/interface/INetworkManager.h): cpp interface · Internal C++ interface boundary used by the plugin. · `interface/INetworkManager.h`
- [Plugin docs](https://github.com/rdkcentral/networkmanager/blob/HEAD/docs/NetworkManagerPlugin.md): documentation · Behavioral documentation for the unified plugin. · `docs/NetworkManagerPlugin.md`

### Thunder host

Plugin entry points, registration, and lifecycle.

- [Module](https://github.com/rdkcentral/networkmanager/blob/HEAD/plugin/Module.cpp): thunder entry · Thunder plugin module entry and registration glue. · `plugin/Module.cpp`
- [Plugin host](https://github.com/rdkcentral/networkmanager/blob/HEAD/plugin/NetworkManager.cpp): thunder plugin · Thunder-facing plugin bootstrap and lifecycle implementation. · `plugin/NetworkManager.cpp`

### Core orchestration

Shared runtime logic for connectivity, STUN, secrets, and logging.

- [Manager impl](https://github.com/rdkcentral/networkmanager/blob/HEAD/plugin/NetworkManagerImplementation.cpp): orchestrator · Main business logic coordinating requests and backend selection. · `plugin/NetworkManagerImplementation.cpp`
- [JSON-RPC map](https://github.com/rdkcentral/networkmanager/blob/HEAD/plugin/NetworkManagerJsonRpc.cpp): rpc adapter · Maps Thunder JSON-RPC calls into internal operations. · `plugin/NetworkManagerJsonRpc.cpp`
- [Connectivity](https://github.com/rdkcentral/networkmanager/blob/HEAD/plugin/NetworkManagerConnectivity.cpp): state engine · Connectivity state, route checks, and reachability assessment. · `plugin/NetworkManagerConnectivity.cpp`
- [STUN client](https://github.com/rdkcentral/networkmanager/blob/HEAD/plugin/NetworkManagerStunClient.cpp): network probe · STUN-based discovery and external reachability checks. · `plugin/NetworkManagerStunClient.cpp`
- [Secret agent](https://github.com/rdkcentral/networkmanager/blob/HEAD/plugin/NetworkManagerSecretAgent.cpp): credential bridge · Handles WiFi credential and secret exchange with the backend. · `plugin/NetworkManagerSecretAgent.cpp`
- [Logger](https://github.com/rdkcentral/networkmanager/blob/HEAD/plugin/NetworkManagerLogger.cpp): logging · Centralized logging for the plugin runtime. · `plugin/NetworkManagerLogger.cpp`

### GNOME backend

GNOME NetworkManager adapter and GDBus integration.

- [GNOME proxy](https://github.com/rdkcentral/networkmanager/blob/HEAD/plugin/gnome/NetworkManagerGnomeProxy.cpp): backend adapter · GNOME-specific adapter layer for the unified API. · `plugin/gnome/NetworkManagerGnomeProxy.cpp`
- [GNOME WiFi](https://github.com/rdkcentral/networkmanager/blob/HEAD/plugin/gnome/NetworkManagerGnomeWIFI.cpp): backend wifi · GNOME backend WiFi management logic. · `plugin/gnome/NetworkManagerGnomeWIFI.cpp`
- [GNOME events](https://github.com/rdkcentral/networkmanager/blob/HEAD/plugin/gnome/NetworkManagerGnomeEvents.cpp): event bridge · Event translation and propagation from GNOME backend. · `plugin/gnome/NetworkManagerGnomeEvents.cpp`
- [GDBus client](https://github.com/rdkcentral/networkmanager/blob/HEAD/plugin/gnome/gdbus/NetworkManagerGdbusClient.cpp): ipc client · GDBus client used to talk to GNOME NetworkManager. · `plugin/gnome/gdbus/NetworkManagerGdbusClient.cpp`
- [GDBus proxy](https://github.com/rdkcentral/networkmanager/blob/HEAD/plugin/gnome/gdbus/NetworkManagerGdbusProxy.cpp): ipc proxy · Proxy layer for GNOME D-Bus communication. · `plugin/gnome/gdbus/NetworkManagerGdbusProxy.cpp`

### RDK backend

RDK Network Service Manager adapter.

- [RDK proxy](https://github.com/rdkcentral/networkmanager/blob/HEAD/plugin/rdk/NetworkManagerRDKProxy.cpp): backend adapter · RDK Network Service Manager adapter. · `plugin/rdk/NetworkManagerRDKProxy.cpp`

### Legacy compatibility

Older Network and WiFiManager surfaces kept for compatibility.

- [Legacy network](https://github.com/rdkcentral/networkmanager/blob/HEAD/legacy/LegacyNetworkAPIs.cpp): compat plugin · Older Network plugin surface retained for compatibility. · `legacy/LegacyNetworkAPIs.cpp`
- [Legacy WiFi](https://github.com/rdkcentral/networkmanager/blob/HEAD/legacy/LegacyWiFiManagerAPIs.cpp): compat plugin · Older WiFiManager plugin surface retained for compatibility. · `legacy/LegacyWiFiManagerAPIs.cpp`

### Support & tests

Tools, test layers, and mock boundaries.

- [L1 tests](https://github.com/rdkcentral/networkmanager/tree/HEAD/tests/l1Test): unit tests · Low-level tests for connectivity, routes, and STUN. · `tests/l1Test`
- [L2 tests](https://github.com/rdkcentral/networkmanager/tree/HEAD/tests/l2Test): integration tests · Backend-specific and legacy-facing integration coverage. · `tests/l2Test`
- [Mocks](https://github.com/rdkcentral/networkmanager/tree/HEAD/tests/mocks): test doubles · Wrappers and mocks for Thunder, GLib, libnm, curl, and IARM. · `tests/mocks`
- [Plugin CLI](https://github.com/rdkcentral/networkmanager/tree/HEAD/tools/plugincli): tooling · Small CLI utilities for exercising backend interfaces. · `tools/plugincli`
- [UPnP tools](https://github.com/rdkcentral/networkmanager/tree/HEAD/tools/upnp): tooling · Router discovery helpers and supporting scripts. · `tools/upnp`

## Connections

- Network API → INetworkManager: defines · The public RPC contract maps to the internal interface boundary.
- Plugin docs → Network API: documents · Docs describe the published JSON-RPC surface.
- Module → Plugin host: boots · Module entry loads and registers the plugin implementation.
- Plugin host → Manager impl: creates · The host layer instantiates the core implementation.
- Manager impl → JSON-RPC map: handles · Implementation delegates request decoding to the JSON-RPC mapper.
- JSON-RPC map → INetworkManager: targets · Mapped operations are expressed through the internal interface.
- Manager impl → Connectivity: uses · Core orchestration consults connectivity state.
- Connectivity → STUN client: probes · Connectivity assessment may trigger STUN-based reachability checks.
- Manager impl → Secret agent: delegates · WiFi credential exchanges are handled by the secret agent.
- Manager impl → Logger: logs · Runtime activity is centralized through the logging layer.
- Manager impl → GNOME proxy: selects · One backend path is the GNOME adapter stack.
- Manager impl → RDK proxy: selects · The alternative backend path is the RDK proxy.
- GNOME proxy → GDBus proxy: bridges · GNOME adapter uses the GDBus proxy layer.
- GDBus proxy → GDBus client: calls · The proxy communicates through the GDBus client.
- GDBus client → GNOME events: receives · Backend state changes are converted into event notifications.
- GNOME proxy → GNOME WiFi: implements · GNOME path includes WiFi-specific behavior.
- GNOME proxy → Secret agent: requests secrets · Secret handling feeds backend authentication flows.
- RDK proxy → Connectivity: reports state · RDK backend participates in connectivity updates.
- Legacy network → Plugin host: compat with · Legacy Network API is retained alongside the new plugin.
- Legacy WiFi → Plugin host: compat with · Legacy WiFiManager API is retained alongside the new plugin.
- L1 tests → Connectivity: covers · L1 tests focus on low-level connectivity behavior.
- L1 tests → STUN client: covers · L1 tests cover STUN and discovery behavior.
- L2 tests → GNOME proxy: covers · Integration tests exercise the GNOME/libnm-style backend path.
- L2 tests → RDK proxy: covers · Integration tests exercise the RDK backend path.
- L2 tests → Legacy network: covers · Legacy tests validate the older Network API surface.
- L2 tests → Legacy WiFi: covers · Legacy tests validate the older WiFiManager API surface.
- Mocks → GDBus client: stubs · Mocks isolate the GDBus and system-library boundaries.
- Mocks → RDK proxy: stubs · Mocks isolate the RDK adapter boundary.
- Plugin CLI → GNOME proxy: exercises · CLI utilities drive backend interface checks.
- UPnP tools → Connectivity: supports · UPnP discovery assists connectivity and router discovery workflows.
