# alptekinsunnetci/pingbox architecture

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

- Interactive diagram: https://gitdiagram.com/alptekinsunnetci/pingbox
- Repository: https://github.com/alptekinsunnetci/pingbox

## Overview

PingBox is an ESP32 network-diagnostics probe. Users connect over its web dashboard or authenticated Telnet CLI, submit diagnostic commands, and receive streamed results; web commands are polled through job endpoints, while Telnet commands stream to the session. A shared job worker dispatches commands to protocol-specific tools. The documented product also includes AP/STA/Hybrid networking, captive setup, persistent settings, logs, and system management. README capabilities inform subsystems whose implementation excerpts were not sampled; their internal wiring is shown only where supported.

Main entry points: [`netmgr.cpp`](https://github.com/alptekinsunnetci/pingbox/blob/main/netmgr.cpp) (Wi-Fi Manager), [`webui.cpp`](https://github.com/alptekinsunnetci/pingbox/blob/main/webui.cpp) (Web Dashboard), [`jobs.cpp`](https://github.com/alptekinsunnetci/pingbox/blob/main/jobs.cpp) (Async Job Engine), [`telnetsrv.cpp`](https://github.com/alptekinsunnetci/pingbox/blob/main/telnetsrv.cpp) (Telnet CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_web["Web Dashboard<br/>[webui.cpp]"]
  node_telnet["Telnet CLI<br/>[telnetsrv.cpp]"]
end

subgraph group_execution["Command Execution"]
  node_cli["Command Parser<br/>[cli.cpp]"]
  node_jobs["Async Job Engine<br/>[jobs.cpp]"]
  node_tools["Diagnostic Tools<br/>[tools.cpp]"]
end

subgraph group_network["Network Services"]
  node_netmgr["Wi-Fi Manager<br/>[netmgr.cpp]"]
  node_captive_dns["Captive DNS<br/>[netmgr.cpp]"]
  node_mdns["mDNS Discovery<br/>[netmgr.cpp]"]
end

subgraph group_state["Device State"]
  node_config["Configuration<br/>[config.cpp]"]
  node_flash[("NVS Flash")]
  node_logs[("Log Buffer<br/>[applog.cpp]")]
end

node_operator(("Network Engineer"))
node_browser(("Web Browser"))
node_telnet_client(("Telnet Client"))
node_network_targets(("Diagnostic Targets"))
node_browser_clients(("Wi-Fi Clients"))
node_device(("ESP32 Device"))

node_operator -->|"uses"| node_browser
node_browser -->|"HTTP requests"| node_web
node_web -->|"submits commands"| node_jobs
node_jobs -->|"executes commands"| node_cli
node_cli -->|"dispatches diagnostics"| node_tools
node_tools -->|"probes protocols"| node_network_targets
node_jobs -->|"streams job output"| node_web
node_telnet_client -->|"connects"| node_telnet
node_telnet -->|"submits commands"| node_jobs
node_telnet -->|"handles job control"| node_jobs
node_jobs -->|"streams job output"| node_telnet
node_telnet -->|"checks credentials"| node_config
node_web -->|"updates settings"| node_config
node_web -->|"reads status, scans Wi-Fi"| node_netmgr
node_web -->|"reads logs"| node_logs
node_cli -->|"reads and saves settings"| node_config
node_cli -->|"reads network status"| node_netmgr
node_netmgr -->|"reads network settings"| node_config
node_config -->|"persists settings"| node_flash
node_netmgr -->|"provides AP or STA"| node_browser_clients
node_netmgr -->|"starts and services"| node_captive_dns
node_netmgr -.->|"announces hostname"| node_mdns
node_device -->|"starts networking"| node_netmgr

click node_web "https://github.com/alptekinsunnetci/pingbox/blob/main/webui.cpp"
click node_telnet "https://github.com/alptekinsunnetci/pingbox/blob/main/telnetsrv.cpp"
click node_cli "https://github.com/alptekinsunnetci/pingbox/blob/main/cli.cpp"
click node_jobs "https://github.com/alptekinsunnetci/pingbox/blob/main/jobs.cpp"
click node_tools "https://github.com/alptekinsunnetci/pingbox/blob/main/tools.cpp"
click node_netmgr "https://github.com/alptekinsunnetci/pingbox/blob/main/netmgr.cpp"
click node_captive_dns "https://github.com/alptekinsunnetci/pingbox/blob/main/netmgr.cpp"
click node_mdns "https://github.com/alptekinsunnetci/pingbox/blob/main/netmgr.cpp"
click node_config "https://github.com/alptekinsunnetci/pingbox/blob/main/config.cpp"
click node_logs "https://github.com/alptekinsunnetci/pingbox/blob/main/applog.cpp"

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_telnet,node_browser,node_telnet_client,node_browser_clients toneBlue
class node_cli,node_jobs,node_tools toneAmber
class node_netmgr,node_captive_dns,node_mdns toneMint
class node_config,node_flash,node_logs toneRose
class node_operator,node_network_targets,node_device toneIndigo
```

## Components

### User Interfaces

- [Web Dashboard](https://github.com/alptekinsunnetci/pingbox/blob/main/webui.cpp): `webui.cpp`
- [Telnet CLI](https://github.com/alptekinsunnetci/pingbox/blob/main/telnetsrv.cpp): `telnetsrv.cpp`

### Command Execution

- [Command Parser](https://github.com/alptekinsunnetci/pingbox/blob/main/cli.cpp): `cli.cpp`
- [Async Job Engine](https://github.com/alptekinsunnetci/pingbox/blob/main/jobs.cpp): `jobs.cpp`
- [Diagnostic Tools](https://github.com/alptekinsunnetci/pingbox/blob/main/tools.cpp): `tools.cpp`

### Network Services

- [Wi-Fi Manager](https://github.com/alptekinsunnetci/pingbox/blob/main/netmgr.cpp): `netmgr.cpp`
- [Captive DNS](https://github.com/alptekinsunnetci/pingbox/blob/main/netmgr.cpp): `netmgr.cpp`
- [mDNS Discovery](https://github.com/alptekinsunnetci/pingbox/blob/main/netmgr.cpp): `netmgr.cpp`

### Device State

- [Configuration](https://github.com/alptekinsunnetci/pingbox/blob/main/config.cpp): `config.cpp`
- **NVS Flash**
- [Log Buffer](https://github.com/alptekinsunnetci/pingbox/blob/main/applog.cpp): `applog.cpp`

### Other components

- **Network Engineer**
- **Web Browser**
- **Telnet Client**
- **Diagnostic Targets**
- **Wi-Fi Clients**
- **ESP32 Device**

## Connections

- Network Engineer → Web Browser: uses
- Web Browser → Web Dashboard: HTTP requests
- Web Dashboard → Async Job Engine: submits commands
- Async Job Engine → Command Parser: executes commands
- Command Parser → Diagnostic Tools: dispatches diagnostics
- Diagnostic Tools → Diagnostic Targets: probes protocols
- Async Job Engine → Web Dashboard: streams job output
- Telnet Client → Telnet CLI: connects
- Telnet CLI → Async Job Engine: submits commands
- Telnet CLI → Async Job Engine: handles job control
- Async Job Engine → Telnet CLI: streams job output
- Telnet CLI → Configuration: checks credentials
- Web Dashboard → Configuration: updates settings
- Web Dashboard → Wi-Fi Manager: reads status, scans Wi-Fi
- Web Dashboard → Log Buffer: reads logs
- Command Parser → Configuration: reads and saves settings
- Command Parser → Wi-Fi Manager: reads network status
- Wi-Fi Manager → Configuration: reads network settings
- Configuration → NVS Flash: persists settings
- Wi-Fi Manager → Wi-Fi Clients: provides AP or STA
- Wi-Fi Manager → Captive DNS: starts and services
- Wi-Fi Manager → mDNS Discovery: announces hostname
- ESP32 Device → Wi-Fi Manager: starts networking