# rdkcentral/unified-wifi-mesh architecture

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

- Interactive diagram: https://gitdiagram.com/rdkcentral/unified-wifi-mesh
- Repository: https://github.com/rdkcentral/unified-wifi-mesh

## Overview

##### Project type and purpose
- This is a native C/C++ networking/control‐plane application implementing the Wi-Fi EasyMesh specification.
- It exposes three main runtime binaries:
- em_agent  – runs on each managed access point
- em_ctrl   – central controller/orchestrator
- em_cli    – command‐line client for operators
- It also includes core libraries (Data Model, EasyMesh logic, abstraction layer) and persistence (DB client).

##### File structure
- Top‐level directories under `src/`:
- agent/     (agent binary implementation)
- ctrl/      (controller binary implementation)
- cli/       (CLI binary, with Go etree parser support)
- cmd/       (command definitions reused by CLI, agent & ctrl)
- db/        (database client abstraction)
- dm/        (Data Model objects: network, device, BSS, policies, etc.)
- em/        (EasyMesh core: discovery, provisioning, steering, state machines)
- orch/      (orchestrator glue between agent & controller)
- util_crypto/ (AES‐SIV library)
- utils/     (shared utilities)
- `inc/` mirrors all public headers.
- `build/`, `Makefile.am`, and GitHub workflows drive CI and cross‐compilation.
- `tests/` contains unit tests using GoogleTest.

##### README and docs
- README points to `docs/UnifiedWifiMesh.pdf`, which describes the EasyMesh state machines and message flows.

##### Main components
a. em_cli (CLI binary)
– User interface to issue commands over IPC (e.g., Unix domain socket or TCP)
b. em_ctrl (Controller)
– Central orchestrator; receives CLI commands, issues control messages to agents
– Houses “orch” layer
c. em_agent (Agent)
– Runs on each managed AP; receives control messages, configures local hardware via Data Model & AL‐SAP
d. Core libraries
– Data Model (`dm/`) – in‐memory representation of networks, radios, SSIDs, stations, policies
– EasyMesh (`em/`) – discovery, provisioning, steering, metrics, SM logic
– AL‐SAP (`al-sap/`) – abstraction layer for IEEE 1905 service access points and data units
– DB client (`db/`) – persists state/events if needed
– Utilities (`utils/`, `util_crypto/`, `cjson_util`)
e. Inter‐process & network interfaces
– IPC (CLI ↔ Controller, Controller ↔ Agent)
– IEEE 1905 messages over the local LAN for discovery & topology sync
f. External systems
– Underlying OS network interfaces, hardware drivers
– Optionally other controllers or management platforms via northbound APIs

##### Relationships & data flows
- User → em_cli → (IPC) → em_ctrl
- em_ctrl → (internal orch APIs) → EasyMesh Control API
- em_ctrl → (IPC or network) → em_agent
- em_agent → DM & AL‐SAP modules → hardware (radio firmware, hostapd, nl80211)
- em_agent → (IEEE 1905) → neighboring agents for topology/discovery
- DM & EM modules exchange events/messages via in‐process queues
- DB client may log events or persist state for replay/testing

##### Architectural patterns
- Layered architecture:
- Presentation (CLI)
- Orchestration (Controller/Orch)
- Core logic (EasyMesh state machines, DM, AL‐SAP)
- Persistence (DB client)
- Modular design: clear separation into libraries & binaries
- Message‐based event handling and state machines
- Reuse of `cmd/` layer to share command definitions

##### Final checklist
- Related modules (e.g., all under “Agent process”) with a lightly shaded container
- External dependencies (OS, drivers, IEEE 1905 network) as boundary elements

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Binaries
    subgraph "CLI Process"
        direction TB
        CLI["em_cli"]:::binary
    end

    subgraph "Controller Process"
        direction TB
        CTRL["em_ctrl"]:::binary
    end

    subgraph "Agent Process"
        direction TB
        AGENT["em_agent"]:::binary
    end

    %% Shared Libraries
    subgraph "Shared Modules"
        direction TB
        CMD["Command Definitions"]:::lib
        DM["Data Model"]:::lib
        EMCORE["EasyMesh Core"]:::lib
        ALSAP["AL-SAP Abstraction"]:::lib
        DBCLIENT["DB Client"]:::lib
        ORCH["Orchestrator Glue"]:::lib
        CRYPTO["Crypto Utilities"]:::lib
        UTILS["Shared Utilities"]:::lib
    end

    %% External Dependencies
    subgraph "External Systems"
        direction TB
        NETHW["OS Network Interface / Drivers"]:::external
        IEEE["IEEE 1905 Network"]:::external
    end

    %% Process Interactions
    CLI -->|"CLI command (IPC)"| CTRL
    CTRL -->|"Control message (IPC/Network)"| AGENT
    AGENT -->|"<-> IEEE 1905 frame"| IEEE
    AGENT -->|"<-> IEEE 1905 frame"| AGENT

    %% Module Usage
    CTRL --> CMD
    CTRL --> ORCH
    CTRL --> DM
    CTRL --> EMCORE
    CTRL --> DBCLIENT
    CTRL --> UTILS

    AGENT --> CMD
    AGENT --> DM
    AGENT --> EMCORE
    AGENT --> ALSAP
    AGENT --> DBCLIENT
    AGENT --> UTILS
    AGENT --> CRYPTO

    %% Hardware interaction
    AGENT -->|"Config API calls"| NETHW
    CTRL --> NETHW

    %% Click Events
    click CLI "https://github.com/rdkcentral/unified-wifi-mesh/tree/main/src/cli"
    click CTRL "https://github.com/rdkcentral/unified-wifi-mesh/tree/main/src/ctrl"
    click AGENT "https://github.com/rdkcentral/unified-wifi-mesh/tree/main/src/agent"
    click CMD "https://github.com/rdkcentral/unified-wifi-mesh/tree/main/src/cmd"
    click DBCLIENT "https://github.com/rdkcentral/unified-wifi-mesh/tree/main/src/db"
    click DM "https://github.com/rdkcentral/unified-wifi-mesh/tree/main/src/dm"
    click EMCORE "https://github.com/rdkcentral/unified-wifi-mesh/tree/main/src/em"
    click ALSAP "https://github.com/rdkcentral/unified-wifi-mesh/tree/main/src/al-sap"
    click ORCH "https://github.com/rdkcentral/unified-wifi-mesh/tree/main/src/orch"
    click CRYPTO "https://github.com/rdkcentral/unified-wifi-mesh/tree/main/src/util_crypto"
    click UTILS "https://github.com/rdkcentral/unified-wifi-mesh/tree/main/src/utils"

    %% Styles
    classDef binary fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef lib fill:#d4edda,stroke:#333,stroke-width:1px
    classDef external fill:#fff3cd,stroke:#333,stroke-width:1px
```
