# bode327/kusumavisionnms architecture

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

- Interactive diagram: https://gitdiagram.com/bode327/kusumavisionnms
- Repository: https://github.com/bode327/kusumavisionnms

## Overview

KusumaVision NMS is an FTTH network management platform for multi-vendor OLTs. Operators use the web UI or REST API to monitor equipment, provision and manage ONUs, and work with alarms, maps, and reports; Android clients provide a mobile path to monitoring and actions. The architecture separates HTTP interfaces, vendor-specific network access, persisted network state, and operational integrations. README statements support several product-level links; sampled source confirms selected service calls, while unsampled subsystems are represented without speculative internal wiring.

Main entry points: [`app/Http/Controllers/SmartOltController.php`](https://github.com/bode327/kusumavisionnms/blob/main/app/Http/Controllers/SmartOltController.php) (Web controllers), [`routes/api.php`](https://github.com/bode327/kusumavisionnms/blob/main/routes/api.php) (REST API v1), [`app/Services/SmartOltSnmpServiceResolver.php`](https://github.com/bode327/kusumavisionnms/blob/main/app/Services/SmartOltSnmpServiceResolver.php) (Vendor selection), [`app/Services/AlarmEvaluator.php`](https://github.com/bode327/kusumavisionnms/blob/main/app/Services/AlarmEvaluator.php) (Alarm evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_web["Web controllers"]
  node_webui["Web UI"]
  node_api["REST API v1<br/>[api.php]"]
  node_mobile["Android app<br/>[MainActivity.kt]"]
end

subgraph group_network["OLT operations"]
  node_vendor["Vendor selection"]
  node_snmp["ZTE SNMP client<br/>[OltSnmpClient.php]"]
  node_hioso["HiOSO driver"]
  node_hsairpo["HsAirPo CLI"]
  node_zteprov["ZTE provisioning"]
  node_support["OLT capabilities"]
  node_poller["Go SNMP poller<br/>[main.go]"]
end

subgraph group_state["Network state"]
  node_oltstate[("OLT inventory<br/>[SnmpOlt.php]")]
  node_onuodp["ONU–ODP mapping<br/>[OnuOdpService.php]"]
  node_mappins[("Map pins<br/>[OnuMapPin.php]")]
  node_user[("Users and roles<br/>[User.php]")]
end

subgraph group_operations["Operations"]
  node_alarms["Alarm evaluation<br/>[AlarmEvaluator.php]"]
  node_telegramnotify["Telegram notifications"]
  node_fcm["FCM push"]
  node_telegrambot["Telegram bot"]
  node_webhook["Webhook management"]
  node_reports["Reports and audit<br/>[ReportService.php]"]
end

subgraph group_integrations["External integrations"]
  node_olt{{"Managed OLTs"}}
  node_telegram{{"Telegram service"}}
  node_androidpush{{"Android devices"}}
end

node_operator(("Network operator"))

node_operator -->|"uses"| node_webui
node_webui -->|"requests"| node_web
node_web -.->|"reads and updates"| node_oltstate
node_web -.->|"resolves driver"| node_vendor
node_web -->|"loads ODP options"| node_onuodp
node_operator -->|"integrates"| node_api
node_api -->|"manages ONUs"| node_olt
node_mobile -->|"calls"| node_api
node_api -->|"uses for ZTE"| node_snmp
node_api -->|"runs actions"| node_zteprov
node_vendor -->|"selects driver"| node_hioso
node_vendor -->|"reads OLT family"| node_oltstate
node_snmp -->|"polls and queries"| node_olt
node_zteprov -->|"provisions ONUs"| node_olt
node_hsairpo -.->|"accesses CLI"| node_olt
node_poller -->|"polls SNMP"| node_olt
node_onuodp -->|"reads and links"| node_mappins
node_web -.->|"serves alarms"| node_alarms
node_alarms -.->|"notifies"| node_telegramnotify
node_alarms -->|"pushes alarms"| node_fcm
node_telegramnotify -->|"sends alerts"| node_telegram
node_telegrambot -->|"reads ONU snapshots"| node_oltstate
node_webhook -->|"registers webhook"| node_telegram
node_androidpush -->|"delivers push"| node_mobile
node_web -.->|"serves reports"| node_reports
node_web -.->|"enforces access"| node_user

click node_web "https://github.com/bode327/kusumavisionnms/blob/main/app/Http/Controllers/SmartOltController.php"
click node_webui "https://github.com/bode327/kusumavisionnms/tree/main/resources/js/Pages/SmartOlt"
click node_api "https://github.com/bode327/kusumavisionnms/blob/main/routes/api.php"
click node_mobile "https://github.com/bode327/kusumavisionnms/blob/main/mobile/android/app/src/main/kotlin/net/kusumavision/kusumavision_nms/MainActivity.kt"
click node_vendor "https://github.com/bode327/kusumavisionnms/blob/main/app/Services/SmartOltSnmpServiceResolver.php"
click node_snmp "https://github.com/bode327/kusumavisionnms/blob/main/app/Services/Snmp/OltSnmpClient.php"
click node_hioso "https://github.com/bode327/kusumavisionnms/blob/main/app/Services/Hioso/HiosoEponSnmpService.php"
click node_hsairpo "https://github.com/bode327/kusumavisionnms/blob/main/app/Services/HsAirPo/HsAirPoCliService.php"
click node_zteprov "https://github.com/bode327/kusumavisionnms/blob/main/app/Services/ZteCliProvisioningExecutor.php"
click node_support "https://github.com/bode327/kusumavisionnms/blob/main/app/Support/SmartOltSupport.php"
click node_poller "https://github.com/bode327/kusumavisionnms/blob/main/cmd/kv-snmp-poller/main.go"
click node_oltstate "https://github.com/bode327/kusumavisionnms/blob/main/app/Models/SnmpOlt.php"
click node_onuodp "https://github.com/bode327/kusumavisionnms/blob/main/app/Services/OnuOdpService.php"
click node_mappins "https://github.com/bode327/kusumavisionnms/blob/main/app/Models/OnuMapPin.php"
click node_alarms "https://github.com/bode327/kusumavisionnms/blob/main/app/Services/AlarmEvaluator.php"
click node_telegramnotify "https://github.com/bode327/kusumavisionnms/blob/main/app/Services/Telegram/TelegramNotifier.php"
click node_fcm "https://github.com/bode327/kusumavisionnms/blob/main/app/Services/Fcm/FcmAlarmNotifier.php"
click node_telegrambot "https://github.com/bode327/kusumavisionnms/blob/main/app/Services/Telegram/TelegramOnuQueryService.php"
click node_webhook "https://github.com/bode327/kusumavisionnms/blob/main/app/Services/Telegram/TelegramWebhookManager.php"
click node_reports "https://github.com/bode327/kusumavisionnms/blob/main/app/Services/Report/ReportService.php"
click node_user "https://github.com/bode327/kusumavisionnms/blob/main/app/Models/User.php"

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_web,node_webui,node_api,node_mobile toneBlue
class node_vendor,node_snmp,node_hioso,node_hsairpo,node_zteprov,node_support,node_poller toneAmber
class node_oltstate,node_onuodp,node_mappins,node_user toneMint
class node_alarms,node_telegramnotify,node_fcm,node_telegrambot,node_webhook,node_reports toneRose
class node_olt,node_telegram,node_androidpush,node_operator toneIndigo
```

## Components

### User interfaces

- [Web controllers](https://github.com/bode327/kusumavisionnms/blob/main/app/Http/Controllers/SmartOltController.php): `app/Http/Controllers/SmartOltController.php`
- [Web UI](https://github.com/bode327/kusumavisionnms/tree/main/resources/js/Pages/SmartOlt): `resources/js/Pages/SmartOlt`
- [REST API v1](https://github.com/bode327/kusumavisionnms/blob/main/routes/api.php): `routes/api.php`
- [Android app](https://github.com/bode327/kusumavisionnms/blob/main/mobile/android/app/src/main/kotlin/net/kusumavision/kusumavision_nms/MainActivity.kt): `mobile/android/app/src/main/kotlin/net/kusumavision/kusumavision_nms/MainActivity.kt`

### OLT operations

- [Vendor selection](https://github.com/bode327/kusumavisionnms/blob/main/app/Services/SmartOltSnmpServiceResolver.php): `app/Services/SmartOltSnmpServiceResolver.php`
- [ZTE SNMP client](https://github.com/bode327/kusumavisionnms/blob/main/app/Services/Snmp/OltSnmpClient.php): `app/Services/Snmp/OltSnmpClient.php`
- [HiOSO driver](https://github.com/bode327/kusumavisionnms/blob/main/app/Services/Hioso/HiosoEponSnmpService.php): `app/Services/Hioso/HiosoEponSnmpService.php`
- [HsAirPo CLI](https://github.com/bode327/kusumavisionnms/blob/main/app/Services/HsAirPo/HsAirPoCliService.php): `app/Services/HsAirPo/HsAirPoCliService.php`
- [ZTE provisioning](https://github.com/bode327/kusumavisionnms/blob/main/app/Services/ZteCliProvisioningExecutor.php): `app/Services/ZteCliProvisioningExecutor.php`
- [OLT capabilities](https://github.com/bode327/kusumavisionnms/blob/main/app/Support/SmartOltSupport.php): `app/Support/SmartOltSupport.php`
- [Go SNMP poller](https://github.com/bode327/kusumavisionnms/blob/main/cmd/kv-snmp-poller/main.go): `cmd/kv-snmp-poller/main.go`

### Network state

- [OLT inventory](https://github.com/bode327/kusumavisionnms/blob/main/app/Models/SnmpOlt.php): `app/Models/SnmpOlt.php`
- [ONU–ODP mapping](https://github.com/bode327/kusumavisionnms/blob/main/app/Services/OnuOdpService.php): `app/Services/OnuOdpService.php`
- [Map pins](https://github.com/bode327/kusumavisionnms/blob/main/app/Models/OnuMapPin.php): `app/Models/OnuMapPin.php`
- [Users and roles](https://github.com/bode327/kusumavisionnms/blob/main/app/Models/User.php): `app/Models/User.php`

### Operations

- [Alarm evaluation](https://github.com/bode327/kusumavisionnms/blob/main/app/Services/AlarmEvaluator.php): `app/Services/AlarmEvaluator.php`
- [Telegram notifications](https://github.com/bode327/kusumavisionnms/blob/main/app/Services/Telegram/TelegramNotifier.php): `app/Services/Telegram/TelegramNotifier.php`
- [FCM push](https://github.com/bode327/kusumavisionnms/blob/main/app/Services/Fcm/FcmAlarmNotifier.php): `app/Services/Fcm/FcmAlarmNotifier.php`
- [Telegram bot](https://github.com/bode327/kusumavisionnms/blob/main/app/Services/Telegram/TelegramOnuQueryService.php): `app/Services/Telegram/TelegramOnuQueryService.php`
- [Webhook management](https://github.com/bode327/kusumavisionnms/blob/main/app/Services/Telegram/TelegramWebhookManager.php): `app/Services/Telegram/TelegramWebhookManager.php`
- [Reports and audit](https://github.com/bode327/kusumavisionnms/blob/main/app/Services/Report/ReportService.php): `app/Services/Report/ReportService.php`

### External integrations

- **Managed OLTs**
- **Telegram service**
- **Android devices**

### Other components

- **Network operator**

## Connections

- Network operator → Web UI: uses (evidence: `README.md`)
- Web UI → Web controllers: requests (evidence: `README.md`)
- Web controllers → OLT inventory: reads and updates (evidence: `app/Http/Controllers/SmartOltController.php`)
- Web controllers → Vendor selection: resolves driver (evidence: `app/Http/Controllers/SmartOltController.php`)
- Web controllers → ONU–ODP mapping: loads ODP options (evidence: `app/Http/Controllers/SmartOltController.php`)
- Network operator → REST API v1: integrates (evidence: `README.md`)
- REST API v1 → Managed OLTs: manages ONUs (evidence: `README.md`)
- Android app → REST API v1: calls (evidence: `README.md`)
- REST API v1 → ZTE SNMP client: uses for ZTE
- REST API v1 → ZTE provisioning: runs actions
- Vendor selection → HiOSO driver: selects driver (evidence: `app/Services/SmartOltSnmpServiceResolver.php`)
- Vendor selection → OLT inventory: reads OLT family (evidence: `app/Services/SmartOltSnmpServiceResolver.php`)
- ZTE SNMP client → Managed OLTs: polls and queries (evidence: `README.md`)
- ZTE provisioning → Managed OLTs: provisions ONUs (evidence: `README.md`)
- HsAirPo CLI → Managed OLTs: accesses CLI
- Go SNMP poller → Managed OLTs: polls SNMP (evidence: `README.md`)
- ONU–ODP mapping → Map pins: reads and links (evidence: `app/Services/OnuOdpService.php`)
- Web controllers → Alarm evaluation: serves alarms
- Alarm evaluation → Telegram notifications: notifies
- Alarm evaluation → FCM push: pushes alarms (evidence: `README.md`)
- Telegram notifications → Telegram service: sends alerts (evidence: `README.md`)
- Telegram bot → OLT inventory: reads ONU snapshots (evidence: `app/Services/Telegram/TelegramOnuQueryService.php`)
- Webhook management → Telegram service: registers webhook (evidence: `app/Services/Telegram/TelegramWebhookManager.php`)
- Android devices → Android app: delivers push (evidence: `README.md`)
- Web controllers → Reports and audit: serves reports
- Web controllers → Users and roles: enforces access