# telecominfraproject/wlan-cloud-ucentralgw architecture

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

- Interactive diagram: https://gitdiagram.com/telecominfraproject/wlan-cloud-ucentralgw
- Repository: https://github.com/telecominfraproject/wlan-cloud-ucentralgw

## Overview

##### Project Type and Purpose
- This is a full-blown C++ microservice (“OpenWiFi Gateway” or OWGW) in the TIP OpenWiFi CloudSDK.
- It mediates between Access Points (APs) speaking the uCentral protocol over WebSockets and northbound clients via a REST/OpenAPI interface.
- It also integrates with Kafka (telemetry/events) and a backing database (MySQL/PostgreSQL via CMake-detected drivers) for persistence.

##### File Structure
- Top-level “src/” contains:
- AP_WS_* modules → manage uCentral WebSocket sessions and message processing.
- RESTAPI/ & RESTObjects/ → HTTP handlers generated from the OpenAPI spec (openapi/owgw.yaml).
- framework/ → generic microservice base, REST servers, WebSocket servers, Kafka manager, event bus, config validator.
- storage/ → CRUD modules for each domain object (devices, firmware, stats, scripts).
- TelemetryClient/KafkaEvents → event publication to Kafka topics defined in KAFKA.md.
- rttys/ & rtty_ui/ → optional CLI Web UI for diagnostics (RTTY).
- Non-code directories:
- Dockerfile, helm/ → container and Kubernetes deployment.
- CMakeLists.txt & cmake/ → cross-platform build and dependency detection (MySQL, PostgreSQL, RdKafka).
- openapi/ & PROTOCOL.md → formal definitions driving codegen.
- cert_scripts/ & certificates/ → TLS artifacts for device‐gateway and REST security.
- test_scripts/ → example CURL and Python automation demonstrating API usage.

##### Insights from README
- OWGW is defined as a microservice with an OpenAPI spec, uses uCentral protocol for device communication, and publishes/consumes Kafka messages.
- It supports two main network interfaces:
a. Southbound: secure WebSocket (wss) on port 15002 to APs.
b. Northbound: HTTPS REST API on port 16002.
- Data flows into internal processors (telemetry, health check, logs, etc.), where domain logic and storage calls happen.

##### Key Components
a. Southbound WebSocket Endpoint (AP_WS_Server)
- Protocol: WSS (port configurable, default 15002)
b. REST/OpenAPI Server
- Protocol: HTTPS (default 16002)
c. Core Processing Modules
- Message Router / Reactor Pool
- CommandManager / ScriptManager
- TelemetryClient & GenericScheduler
- EventBusManager & KafkaManager
d. Storage Layer
- “StorageService” calling SQL backends (MySQL/PostgreSQL)
- Domain stores (devices, configs, scripts, logs, stats)
e. Kafka Cluster
- Topics for telemetry, events, commands
f. RTTY UI (optional)
- Local Web interface served by RTTYS_WebServer
g. Auxiliary
- Configuration files (owgw.properties)
- TLS Certificates (server, REST, client CAs)
- Helm / Docker / systemd for deployment

##### Relationships & Data Flows
- APs → (WSS) → AP_WS_Server → ReactorPool → Domain Processors → StorageService & KafkaManager → Kafka
- REST Clients → (HTTPS) → RESTAPI Server → REST Handlers → StorageService / CommandManager
- ScriptManager publishes scripts to AP via AP_WS_Connection
- TelemetryClient consumes AP events, publishes to Kafka
- RTTY UI ← WebSocket ← UI_GW_WebSocketNotifications
- All modules retrieve config from CentralConfig via ConfigurationCache

##### Architectural Patterns & Design Principles
- Microservice base class enforces consistent startup, health checks, metrics.
- Event‐driven: EventBusManager decouples producers and consumers.
- Modular layering: framework → core processors → storage → external systems.
- Codegen for REST/Objects ensures schema‐driven consistency.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Clients
    APs["APs<br/>(uCentral Devices)"]:::external
    RESTClients["REST Clients"]:::external
    CLIUI["RTTY CLI/Web UI"]:::external

    %% OWGW Service
    subgraph "OWGW Microservice"
        subgraph "Interfaces" 
            WS["uCentral WebSocket Server<br/>WSS 15002"]:::interfaces
            RESTAPI["REST API Server<br/>HTTPS 16002"]:::interfaces
        end

        subgraph "Core Engine"
            Reactor["Reactor Pool / Message Router"]:::core
            CmdMgr["Command Manager"]:::core
            ScriptMgr["Script Manager"]:::core
            Telemetry["Telemetry Client & Generic Scheduler"]:::core
        end

        subgraph "Framework"
            EventBus["EventBus Manager"]:::framework
            KafkaMgr["Kafka Manager"]:::framework
            Config["Auth & Config Validator"]:::framework
        end

        subgraph "Storage Layer"
            Storage["Storage Service"]:::storage
        end
    end

    %% Infrastructure
    KafkaCluster["Kafka Cluster<br/>(topics: telemetry, events, commands)"]:::external
    SQLDB["SQL Database<br/>(MySQL/PostgreSQL)"]:::external

    %% Connections
    APs -- "WSS" --> WS
    WS --> Reactor
    Reactor --> CmdMgr
    Reactor --> ScriptMgr
    Reactor --> Telemetry
    CmdMgr --> Storage
    ScriptMgr --> WS
    Telemetry --> KafkaCluster
    Reactor --> Storage
    EventBus <-- Reactor
    EventBus --> KafkaMgr
    KafkaMgr --> KafkaCluster
    RESTClients -- "HTTPS" --> RESTAPI
    RESTAPI --> Config
    RESTAPI --> Storage
    RESTAPI --> CmdMgr
    CLIUI -- "WebSocket" --> WS

    Storage -- "SQL" --> SQLDB

    %% Click Events
    click WS "https://github.com/telecominfraproject/wlan-cloud-ucentralgw/blob/master/src/AP_WS_Server.cpp"
    click Reactor "https://github.com/telecominfraproject/wlan-cloud-ucentralgw/blob/master/src/AP_WS_Reactor_Pool.h"
    click CmdMgr "https://github.com/telecominfraproject/wlan-cloud-ucentralgw/blob/master/src/CommandManager.cpp"
    click ScriptMgr "https://github.com/telecominfraproject/wlan-cloud-ucentralgw/blob/master/src/ScriptManager.cpp"
    click Telemetry "https://github.com/telecominfraproject/wlan-cloud-ucentralgw/blob/master/src/TelemetryClient.cpp"
    click EventBus "https://github.com/telecominfraproject/wlan-cloud-ucentralgw/blob/master/src/framework/EventBusManager.cpp"
    click KafkaMgr "https://github.com/telecominfraproject/wlan-cloud-ucentralgw/blob/master/src/framework/KafkaManager.cpp"
    click Storage "https://github.com/telecominfraproject/wlan-cloud-ucentralgw/blob/master/src/StorageService.cpp"
    click RESTAPI "https://github.com/telecominfraproject/wlan-cloud-ucentralgw/blob/master/src/framework/RESTAPI_ExtServer.cpp"
    click CLIUI "https://github.com/telecominfraproject/wlan-cloud-ucentralgw/tree/master/rtty_ui/"

    %% Styles
    classDef external fill:#eeeeee,stroke:#333,stroke-width:1px
    classDef interfaces fill:#add8e6,stroke:#333,stroke-width:1px
    classDef core fill:#90ee90,stroke:#333,stroke-width:1px
    classDef framework fill:#ffa500,stroke:#333,stroke-width:1px
    classDef storage fill:#d3d3d3,stroke:#333,stroke-width:1px
```
