# routerarchitects/ra-wlan-cloud-analytics architecture

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

- Interactive diagram: https://gitdiagram.com/routerarchitects/ra-wlan-cloud-analytics
- Repository: https://github.com/routerarchitects/ra-wlan-cloud-analytics

## Overview

#### Purpose and entry points
OWANALYTICS is a C++ OpenWiFi/Mango Cloud microservice that ingests AP telemetry, derives device/venue/client metrics, persists historical analytics, and exposes them through REST APIs. Build and process entry wiring are centered on `CMakeLists.txt`, `src/Daemon.cpp`, and `src/framework/MicroService.cpp`. Its public contract is `openapi/owanalytics.yaml`.

#### Service runtime and network boundary
The daemon runs three configurable interfaces: public REST (default 16009), internal REST (17009), and ALB health checks (16109). The framework separates public/internal servers and load-balancer health handling in `src/framework/RESTAPI_ExtServer.cpp`, `src/framework/RESTAPI_IntServer.cpp`, and `src/framework/ALBserver.cpp`. Configuration is supplied through `owanalytics.properties` (with template `owanalytics.properties.tmpl`).

#### Telemetry ingestion and event coordination
Kafka is the primary asynchronous integration boundary for device telemetry and microservice coordination. `src/framework/KafkaManager.cpp` and `src/framework/EventBusManager.cpp` provide messaging infrastructure; topic definitions reside in `src/framework/KafkaTopics.h`. Domain receivers—`src/DeviceStatusReceiver.cpp`, `src/HealthReceiver.cpp`, and `src/StateReceiver.cpp`—consume and interpret AP status, health, and state streams.

#### Analytics aggregation and lifecycle
`src/APStats.cpp` is the core AP-statistics aggregation model. `src/Dashboard.cpp` and `src/VenueCoordinator.cpp` organize telemetry into operational/venue-level views, while `src/VenueWatcher.cpp` tracks venue-related changes. A likely primary flow is: Kafka telemetry → receivers → AP/client/venue aggregation → storage and API-visible summaries.

#### Client telemetry and historical persistence
Wi-Fi client association and radio/bandwidth history are maintained through `src/WifiClientCache.cpp` and persisted by `src/storage/storage_wificlients.cpp`. Device and time-series persistence are separated into `src/storage/storage_boards.cpp` and `src/storage/storage_timepoints.cpp`; `src/StorageService.cpp` coordinates the storage layer. PostgreSQL and MySQL are material build/runtime integration points, indicated by `cmake/FindPostgreSQL.cmake` and `cmake/FindMySQL.cmake`.

#### API composition and downstream integrations
Analytics REST routing is centralized in `src/RESTAPI/RESTAPI_routers.cpp`. Board/device, timepoint, and client-history query handlers live in `src/RESTAPI/RESTAPI_board_handler.cpp`, `src/RESTAPI/RESTAPI_board_timepoint_handler.cpp`, and `src/RESTAPI/RESTAPI_wificlienthistory_handler.cpp`. Typed request/response models for peer OpenWiFi services are in `src/RESTObjects/`, while `src/framework/AuthClient.cpp` enforces intra-service authentication via OWSEC tokens and `src/sdks/SDK_prov.cpp` integrates provisioning context.

#### Deployment and operations
The service is containerized by `Dockerfile` and `docker-entrypoint.sh`, with PostgreSQL startup coordination in `wait-for-postgres.sh`. Kubernetes deployment is packaged as a Helm chart, primarily `helm/templates/deployment.yaml`, `helm/templates/service.yaml`, and `helm/templates/ingress.yaml`. The system runs within the broader OWSDK ecosystem, notably OWGW as telemetry/controller source, OWSEC for auth, and OWPROV for provisioning/venue relationships.

Main entry points: [`src/StorageService.cpp`](https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/StorageService.cpp) (Storage Service), [`src/RESTAPI/RESTAPI_routers.cpp`](https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/RESTAPI/RESTAPI_routers.cpp) (Analytics API Router), [`src/framework/MicroService.cpp`](https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/framework/MicroService.cpp) (Microservice Framework), [`src/APStats.cpp`](https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/APStats.cpp) (AP Statistics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Service Runtime"]
  node_build["CMake Build<br/>[CMakeLists.txt]"]
  node_daemon["Daemon<br/>process entry<br/>[Daemon.cpp]"]
  node_microservice["Microservice Framework<br/>runtime framework<br/>[MicroService.cpp]"]
  node_rest_servers["REST Server Interfaces<br/>network boundary"]
end

subgraph group_ingestion["Telemetry Ingestion"]
  node_kafka["Kafka Event Bus<br/>messaging<br/>[KafkaManager.cpp]"]
  node_topic_definitions["Kafka Topics<br/>topic contract<br/>[KafkaTopics.h]"]
  node_telemetry_receivers["Telemetry Receivers<br/>event consumers"]
end

subgraph group_analytics["Analytics"]
  node_ap_stats["AP Statistics<br/>aggregation model<br/>[APStats.cpp]"]
  node_venue_analytics["Venue Analytics<br/>venue coordinator"]
  node_client_cache["Wi-Fi Client Cache<br/>client history"]
end

subgraph group_persistence["Historical Storage"]
  node_storage_service["Storage Service<br/>persistence coordinator<br/>[StorageService.cpp]"]
  node_client_storage[("Client History Storage<br/>storage adapter")]
  node_metrics_storage[("Device &amp; Time-Series Storage<br/>storage adapters")]
  node_databases[("PostgreSQL / MySQL<br/>databases")]
end

subgraph group_api["API &amp; Integrations"]
  node_api_router["Analytics API Router<br/>REST routing"]
  node_api_handlers["Analytics Query Handlers<br/>REST handlers"]
  node_auth_client["OWSEC Auth Client<br/>service authentication<br/>[AuthClient.cpp]"]
  node_provisioning_sdk["OWPROV SDK<br/>downstream integration<br/>[SDK_prov.cpp]"]
  node_openapi["OpenAPI Contract<br/>[owanalytics.yaml]"]
end

subgraph group_deployment["Deployment"]
  node_container_deployment{{"Container &amp; Helm Deployment"}}
end

node_build -->|"builds"| node_daemon
node_daemon -->|"starts"| node_microservice
node_microservice -->|"hosts"| node_rest_servers
node_microservice -->|"initializes"| node_kafka
node_topic_definitions -->|"defines"| node_kafka
node_kafka -->|"telemetry events"| node_telemetry_receivers
node_telemetry_receivers -->|"updates"| node_ap_stats
node_ap_stats -->|"aggregates into"| node_venue_analytics
node_ap_stats -->|"updates client history"| node_client_cache
node_venue_analytics -->|"persists summaries"| node_storage_service
node_client_cache -->|"persists history"| node_storage_service
node_storage_service -->|"writes"| node_client_storage
node_storage_service -->|"writes"| node_metrics_storage
node_client_storage -->|"stores in"| node_databases
node_metrics_storage -->|"stores in"| node_databases
node_rest_servers -->|"routes requests"| node_api_router
node_api_router -->|"dispatches"| node_api_handlers
node_api_handlers -->|"queries historical data"| node_storage_service
node_api_router -->|"implements"| node_openapi
node_api_router -->|"authenticates"| node_auth_client
node_venue_analytics -->|"gets venue context"| node_provisioning_sdk
node_container_deployment -->|"deploys"| node_daemon

click node_build "https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/CMakeLists.txt"
click node_daemon "https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/Daemon.cpp"
click node_microservice "https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/framework/MicroService.cpp"
click node_rest_servers "https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/framework/RESTAPI_ExtServer.cpp"
click node_kafka "https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/framework/KafkaManager.cpp"
click node_topic_definitions "https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/framework/KafkaTopics.h"
click node_telemetry_receivers "https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/DeviceStatusReceiver.cpp"
click node_ap_stats "https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/APStats.cpp"
click node_venue_analytics "https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/VenueCoordinator.cpp"
click node_client_cache "https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/WifiClientCache.cpp"
click node_storage_service "https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/StorageService.cpp"
click node_client_storage "https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/storage/storage_wificlients.cpp"
click node_metrics_storage "https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/storage/storage_timepoints.cpp"
click node_api_router "https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/RESTAPI/RESTAPI_routers.cpp"
click node_api_handlers "https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/RESTAPI/RESTAPI_board_handler.cpp"
click node_auth_client "https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/framework/AuthClient.cpp"
click node_provisioning_sdk "https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/sdks/SDK_prov.cpp"
click node_openapi "https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/openapi/owanalytics.yaml"
click node_container_deployment "https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/Dockerfile"

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 node_build,node_daemon,node_microservice,node_rest_servers toneBlue
class node_kafka,node_topic_definitions,node_telemetry_receivers toneAmber
class node_ap_stats,node_venue_analytics,node_client_cache toneMint
class node_storage_service,node_client_storage,node_metrics_storage,node_databases toneRose
class node_api_router,node_api_handlers,node_auth_client,node_provisioning_sdk,node_openapi toneIndigo
class node_container_deployment toneTeal
```

## Components

### Service Runtime

- [CMake Build](https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/CMakeLists.txt): build · `CMakeLists.txt`
- [Daemon](https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/Daemon.cpp): process entry · Starts the analytics microservice. · `src/Daemon.cpp`
- [Microservice Framework](https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/framework/MicroService.cpp): runtime framework · Owns service lifecycle and wiring. · `src/framework/MicroService.cpp`
- [REST Server Interfaces](https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/framework/RESTAPI_ExtServer.cpp): network boundary · Separates public, internal, and ALB health endpoints. · `src/framework/RESTAPI_ExtServer.cpp`

### Telemetry Ingestion

- [Kafka Event Bus](https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/framework/KafkaManager.cpp): messaging · Primary asynchronous telemetry and coordination boundary. · `src/framework/KafkaManager.cpp`
- [Kafka Topics](https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/framework/KafkaTopics.h): topic contract · `src/framework/KafkaTopics.h`
- [Telemetry Receivers](https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/DeviceStatusReceiver.cpp): event consumers · Interprets device status, health, and state streams. · `src/DeviceStatusReceiver.cpp`

### Analytics

- [AP Statistics](https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/APStats.cpp): aggregation model · Core AP and client telemetry aggregation. · `src/APStats.cpp`
- [Venue Analytics](https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/VenueCoordinator.cpp): venue coordinator · Builds operational and venue-level views. · `src/VenueCoordinator.cpp`
- [Wi-Fi Client Cache](https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/WifiClientCache.cpp): client history · Maintains association, radio, and bandwidth history. · `src/WifiClientCache.cpp`

### Historical Storage

- [Storage Service](https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/StorageService.cpp): persistence coordinator · Coordinates device, time-series, and client persistence. · `src/StorageService.cpp`
- [Client History Storage](https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/storage/storage_wificlients.cpp): storage adapter · `src/storage/storage_wificlients.cpp`
- [Device & Time-Series Storage](https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/storage/storage_timepoints.cpp): storage adapters · `src/storage/storage_timepoints.cpp`
- **PostgreSQL / MySQL**: databases · Runtime historical analytics stores.

### API & Integrations

- [Analytics API Router](https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/RESTAPI/RESTAPI_routers.cpp): REST routing · Composes analytics query endpoints. · `src/RESTAPI/RESTAPI_routers.cpp`
- [Analytics Query Handlers](https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/RESTAPI/RESTAPI_board_handler.cpp): REST handlers · Serves board, timepoint, and client-history queries. · `src/RESTAPI/RESTAPI_board_handler.cpp`
- [OWSEC Auth Client](https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/framework/AuthClient.cpp): service authentication · Uses OWSEC tokens for intra-service authentication. · `src/framework/AuthClient.cpp`
- [OWPROV SDK](https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/src/sdks/SDK_prov.cpp): downstream integration · Obtains provisioning and venue context. · `src/sdks/SDK_prov.cpp`
- [OpenAPI Contract](https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/openapi/owanalytics.yaml): API contract · `openapi/owanalytics.yaml`

### Deployment

- [Container & Helm Deployment](https://github.com/routerarchitects/ra-wlan-cloud-analytics/blob/main/Dockerfile): deployment · Packages the service and Kubernetes resources. · `Dockerfile`

## Connections

- CMake Build → Daemon: builds
- Daemon → Microservice Framework: starts
- Microservice Framework → REST Server Interfaces: hosts
- Microservice Framework → Kafka Event Bus: initializes
- Kafka Topics → Kafka Event Bus: defines
- Kafka Event Bus → Telemetry Receivers: telemetry events
- Telemetry Receivers → AP Statistics: updates
- AP Statistics → Venue Analytics: aggregates into
- AP Statistics → Wi-Fi Client Cache: updates client history
- Venue Analytics → Storage Service: persists summaries
- Wi-Fi Client Cache → Storage Service: persists history
- Storage Service → Client History Storage: writes
- Storage Service → Device & Time-Series Storage: writes
- Client History Storage → PostgreSQL / MySQL: stores in
- Device & Time-Series Storage → PostgreSQL / MySQL: stores in
- REST Server Interfaces → Analytics API Router: routes requests
- Analytics API Router → Analytics Query Handlers: dispatches
- Analytics Query Handlers → Storage Service: queries historical data
- Analytics API Router → OpenAPI Contract: implements
- Analytics API Router → OWSEC Auth Client: authenticates
- Venue Analytics → OWPROV SDK: gets venue context
- Container & Helm Deployment → Daemon: deploys