# knbgull/nbgvox architecture

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

- Interactive diagram: https://gitdiagram.com/knbgull/nbgvox
- Repository: https://github.com/knbgull/nbgvox

## Overview

NbgVox is an embeddable Java monitoring module that exposes host-process status through HTTP. The main workflow is host attachment (directly or as a JVM agent), configuration and runtime initialization, then browser requests to status, JSON, or JVM-detail endpoints. Runtime data includes CPU/thread metrics and registered extension fields; the documented access-sensitive user logging capability is also represented. Several edges rely on source-index references rather than complete excerpts, so uncertain internal wiring is omitted.

Main entry points: [`src/main/java/knbgulll/nbgvox/vox/NbgVox.java`](https://github.com/knbgull/nbgvox/blob/main/src/main/java/knbgulll/nbgvox/vox/NbgVox.java) (Attach lifecycle), [`src/main/java/knbgulll/nbgvox/vox/data/RuntimeInfo.java`](https://github.com/knbgull/nbgvox/blob/main/src/main/java/knbgulll/nbgvox/vox/data/RuntimeInfo.java) (Runtime metrics), [`src/main/java/knbgulll/nbgvox/vox/NbgVoxServer.java`](https://github.com/knbgull/nbgvox/blob/main/src/main/java/knbgulll/nbgvox/vox/NbgVoxServer.java) (HTTP server), [`src/main/java/knbgulll/nbgvox/vox/handler/StatusHandler.java`](https://github.com/knbgull/nbgvox/blob/main/src/main/java/knbgulll/nbgvox/vox/handler/StatusHandler.java) (Status page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Startup and configuration"]
  node_agent["JVM agent<br/>[NbgVoxAgent.java]"]
  node_attach["Attach lifecycle<br/>[NbgVox.java]"]
  node_config["Configuration<br/>[NbgVoxConfig.java]"]
  node_defaults["Bundled defaults"]
end

subgraph group_monitoring["Runtime monitoring"]
  node_runtime["Runtime metrics<br/>[RuntimeInfo.java]"]
end

subgraph group_web["HTTP presentation"]
  node_server["HTTP server<br/>[NbgVoxServer.java]"]
  node_redirect["Root redirect"]
  node_status["Status page<br/>[StatusHandler.java]"]
  node_json["Status JSON"]
  node_jvm["JVM detail tree<br/>[JvmAllHandler.java]"]
end

subgraph group_extensions["Extensions and logging"]
  node_registry["Provider registry"]
  node_provider["Custom data provider"]
  node_syslog["System logger<br/>[SystemLogger.java]"]
  node_userlog["User activity logger<br/>[UserLogger.java]"]
  node_writer["Rotating log writer<br/>[LogWriter.java]"]
end

node_host(("Host application"))
node_browser(("Browser user"))

node_host -->|"attaches"| node_attach
node_agent -->|"starts"| node_attach
node_attach -->|"loads"| node_config
node_config -->|"loads defaults"| node_defaults
node_attach -->|"initializes"| node_runtime
node_attach -->|"creates"| node_registry
node_attach -->|"starts"| node_server
node_attach -->|"creates"| node_syslog
node_attach -->|"creates"| node_userlog
node_server -->|"routes root"| node_redirect
node_server -->|"routes status"| node_status
node_server -->|"routes JSON"| node_json
node_server -->|"routes details"| node_jvm
node_browser -->|"requests page"| node_status
node_browser -->|"requests data"| node_json
node_browser -->|"requests details"| node_jvm
node_status -->|"fetches updates"| node_json
node_status -->|"reads metrics"| node_runtime
node_json -->|"reads metrics"| node_runtime
node_jvm -->|"samples runtime"| node_runtime
node_runtime -->|"reads settings"| node_config
node_runtime -->|"reads providers"| node_registry
node_registry -->|"registers providers"| node_provider
node_status -->|"renders fields"| node_provider
node_syslog -->|"writes entries"| node_writer
node_userlog -->|"writes entries"| node_writer

click node_agent "https://github.com/knbgull/nbgvox/blob/main/src/main/java/knbgulll/nbgvox/vox/agent/NbgVoxAgent.java"
click node_attach "https://github.com/knbgull/nbgvox/blob/main/src/main/java/knbgulll/nbgvox/vox/NbgVox.java"
click node_config "https://github.com/knbgull/nbgvox/blob/main/src/main/java/knbgulll/nbgvox/vox/NbgVoxConfig.java"
click node_defaults "https://github.com/knbgull/nbgvox/blob/main/src/main/resources/META-INF/nbgvox-default.properties"
click node_server "https://github.com/knbgull/nbgvox/blob/main/src/main/java/knbgulll/nbgvox/vox/NbgVoxServer.java"
click node_redirect "https://github.com/knbgull/nbgvox/blob/main/src/main/java/knbgulll/nbgvox/vox/handler/RootRedirectHandler.java"
click node_status "https://github.com/knbgull/nbgvox/blob/main/src/main/java/knbgulll/nbgvox/vox/handler/StatusHandler.java"
click node_json "https://github.com/knbgull/nbgvox/blob/main/src/main/java/knbgulll/nbgvox/vox/handler/JsonStatusHandler.java"
click node_jvm "https://github.com/knbgull/nbgvox/blob/main/src/main/java/knbgulll/nbgvox/vox/handler/JvmAllHandler.java"
click node_runtime "https://github.com/knbgull/nbgvox/blob/main/src/main/java/knbgulll/nbgvox/vox/data/RuntimeInfo.java"
click node_registry "https://github.com/knbgull/nbgvox/blob/main/src/main/java/knbgulll/nbgvox/vox/NbgVoxRegistry.java"
click node_provider "https://github.com/knbgull/nbgvox/blob/main/src/main/java/knbgulll/nbgvox/vox/data/NbgVoxDataProvider.java"
click node_syslog "https://github.com/knbgull/nbgvox/blob/main/src/main/java/knbgulll/nbgvox/vox/log/SystemLogger.java"
click node_userlog "https://github.com/knbgull/nbgvox/blob/main/src/main/java/knbgulll/nbgvox/vox/log/UserLogger.java"
click node_writer "https://github.com/knbgull/nbgvox/blob/main/src/main/java/knbgulll/nbgvox/vox/log/LogWriter.java"

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_agent,node_attach,node_config,node_defaults,node_browser toneBlue
class node_runtime toneAmber
class node_server,node_redirect,node_status,node_json,node_jvm toneMint
class node_registry,node_provider,node_syslog,node_userlog,node_writer toneRose
class node_host toneIndigo
```

## Components

### Startup and configuration

- [JVM agent](https://github.com/knbgull/nbgvox/blob/main/src/main/java/knbgulll/nbgvox/vox/agent/NbgVoxAgent.java): `src/main/java/knbgulll/nbgvox/vox/agent/NbgVoxAgent.java`
- [Attach lifecycle](https://github.com/knbgull/nbgvox/blob/main/src/main/java/knbgulll/nbgvox/vox/NbgVox.java): `src/main/java/knbgulll/nbgvox/vox/NbgVox.java`
- [Configuration](https://github.com/knbgull/nbgvox/blob/main/src/main/java/knbgulll/nbgvox/vox/NbgVoxConfig.java): `src/main/java/knbgulll/nbgvox/vox/NbgVoxConfig.java`
- [Bundled defaults](https://github.com/knbgull/nbgvox/blob/main/src/main/resources/META-INF/nbgvox-default.properties): `src/main/resources/META-INF/nbgvox-default.properties`

### Runtime monitoring

- [Runtime metrics](https://github.com/knbgull/nbgvox/blob/main/src/main/java/knbgulll/nbgvox/vox/data/RuntimeInfo.java): `src/main/java/knbgulll/nbgvox/vox/data/RuntimeInfo.java`

### HTTP presentation

- [HTTP server](https://github.com/knbgull/nbgvox/blob/main/src/main/java/knbgulll/nbgvox/vox/NbgVoxServer.java): `src/main/java/knbgulll/nbgvox/vox/NbgVoxServer.java`
- [Root redirect](https://github.com/knbgull/nbgvox/blob/main/src/main/java/knbgulll/nbgvox/vox/handler/RootRedirectHandler.java): `src/main/java/knbgulll/nbgvox/vox/handler/RootRedirectHandler.java`
- [Status page](https://github.com/knbgull/nbgvox/blob/main/src/main/java/knbgulll/nbgvox/vox/handler/StatusHandler.java): `src/main/java/knbgulll/nbgvox/vox/handler/StatusHandler.java`
- [Status JSON](https://github.com/knbgull/nbgvox/blob/main/src/main/java/knbgulll/nbgvox/vox/handler/JsonStatusHandler.java): `src/main/java/knbgulll/nbgvox/vox/handler/JsonStatusHandler.java`
- [JVM detail tree](https://github.com/knbgull/nbgvox/blob/main/src/main/java/knbgulll/nbgvox/vox/handler/JvmAllHandler.java): `src/main/java/knbgulll/nbgvox/vox/handler/JvmAllHandler.java`

### Extensions and logging

- [Provider registry](https://github.com/knbgull/nbgvox/blob/main/src/main/java/knbgulll/nbgvox/vox/NbgVoxRegistry.java): `src/main/java/knbgulll/nbgvox/vox/NbgVoxRegistry.java`
- [Custom data provider](https://github.com/knbgull/nbgvox/blob/main/src/main/java/knbgulll/nbgvox/vox/data/NbgVoxDataProvider.java): `src/main/java/knbgulll/nbgvox/vox/data/NbgVoxDataProvider.java`
- [System logger](https://github.com/knbgull/nbgvox/blob/main/src/main/java/knbgulll/nbgvox/vox/log/SystemLogger.java): `src/main/java/knbgulll/nbgvox/vox/log/SystemLogger.java`
- [User activity logger](https://github.com/knbgull/nbgvox/blob/main/src/main/java/knbgulll/nbgvox/vox/log/UserLogger.java): `src/main/java/knbgulll/nbgvox/vox/log/UserLogger.java`
- [Rotating log writer](https://github.com/knbgull/nbgvox/blob/main/src/main/java/knbgulll/nbgvox/vox/log/LogWriter.java): `src/main/java/knbgulll/nbgvox/vox/log/LogWriter.java`

### Other components

- **Host application**
- **Browser user**

## Connections

- Host application → Attach lifecycle: attaches (evidence: `README.md`)
- JVM agent → Attach lifecycle: starts (evidence: `src/main/java/knbgulll/nbgvox/vox/agent/NbgVoxAgent.java`)
- Attach lifecycle → Configuration: loads (evidence: `src/main/java/knbgulll/nbgvox/vox/NbgVox.java`)
- Configuration → Bundled defaults: loads defaults (evidence: `src/main/java/knbgulll/nbgvox/vox/NbgVoxConfig.java`)
- Attach lifecycle → Runtime metrics: initializes (evidence: `src/main/java/knbgulll/nbgvox/vox/NbgVox.java`)
- Attach lifecycle → Provider registry: creates (evidence: `src/main/java/knbgulll/nbgvox/vox/NbgVox.java`)
- Attach lifecycle → HTTP server: starts (evidence: `src/main/java/knbgulll/nbgvox/vox/NbgVox.java`)
- Attach lifecycle → System logger: creates (evidence: `src/main/java/knbgulll/nbgvox/vox/NbgVox.java`)
- Attach lifecycle → User activity logger: creates (evidence: `src/main/java/knbgulll/nbgvox/vox/NbgVox.java`)
- HTTP server → Root redirect: routes root (evidence: `src/main/java/knbgulll/nbgvox/vox/NbgVoxServer.java`)
- HTTP server → Status page: routes status (evidence: `src/main/java/knbgulll/nbgvox/vox/NbgVoxServer.java`)
- HTTP server → Status JSON: routes JSON (evidence: `src/main/java/knbgulll/nbgvox/vox/NbgVoxServer.java`)
- HTTP server → JVM detail tree: routes details (evidence: `src/main/java/knbgulll/nbgvox/vox/NbgVoxServer.java`)
- Browser user → Status page: requests page (evidence: `README.md`)
- Browser user → Status JSON: requests data (evidence: `README.md`)
- Browser user → JVM detail tree: requests details (evidence: `README.md`)
- Status page → Status JSON: fetches updates (evidence: `src/main/java/knbgulll/nbgvox/vox/handler/StatusHandler.java`)
- Status page → Runtime metrics: reads metrics (evidence: `src/main/java/knbgulll/nbgvox/vox/handler/StatusHandler.java`)
- Status JSON → Runtime metrics: reads metrics (evidence: `src/main/java/knbgulll/nbgvox/vox/handler/JsonStatusHandler.java`)
- JVM detail tree → Runtime metrics: samples runtime (evidence: `src/main/java/knbgulll/nbgvox/vox/handler/JvmAllHandler.java`)
- Runtime metrics → Configuration: reads settings (evidence: `src/main/java/knbgulll/nbgvox/vox/data/RuntimeInfo.java`)
- Runtime metrics → Provider registry: reads providers (evidence: `src/main/java/knbgulll/nbgvox/vox/data/RuntimeInfo.java`)
- Provider registry → Custom data provider: registers providers (evidence: `src/main/java/knbgulll/nbgvox/vox/NbgVoxRegistry.java`)
- Status page → Custom data provider: renders fields (evidence: `src/main/java/knbgulll/nbgvox/vox/handler/StatusHandler.java`)
- System logger → Rotating log writer: writes entries (evidence: `src/main/java/knbgulll/nbgvox/vox/log/SystemLogger.java`)
- User activity logger → Rotating log writer: writes entries (evidence: `src/main/java/knbgulll/nbgvox/vox/log/UserLogger.java`)