Monitor Agent & Fleet Management Platform

Monitor Agent is an end-to-end multi-tenant infrastructure monitoring platform featuring live time-series telemetry streaming, deep diagnostic system snapshots, and bi-directional remote command execution. It couples a Spring Boot 4.0.2 / Java 21 backend with TimescaleDB time-series storage, a Next.js 16 (React 19) dashboard, a native Go daemon/CLI agent, and a high-concurrency simulation load tester.

---

Technical Documentation Suite

The complete code-first technical documentation and architectural reverse-engineering reference is maintained in the docs/ directory:

Document	Primary Focus
System Overview	High-level system architecture, subsystem inventory, and core invariants.
System Architecture	Full architectural diagrams, process models, and trust boundaries.
Execution Traces	Concrete end-to-end traces for metric collection, failures, commands, and sweeps.
Go Monitor Agent	Internal agent engine, gopsutil collectors, adaptive loop, and STOMP client.
Go CLI Reference	Comprehensive reference for Cobra CLI commands, flags, and exit codes.
Spring Boot Backend	Controller forensics, services, security filters, and TimescaleDB initialization.
Next.js Frontend	React 19 state, SockJS/STOMP streaming, and multi-chunk command reassembly.
Data Flow & Lineage	End-to-end metric transformation from OS kernel counters to SVG chart rendering.
Networking & Protocols	Protocols, STOMP framing, transport buffer limits, and dual WebSocket topology.
Batching & Rate Limiting	Thresholds, memory ownership, edge rate limiting, and exemption rules.
Concurrency & Threading	Goroutines, thread pools, race condition analysis, and synchronization hazards.
Database & TimescaleDB	Schema ERD, hypertable partition mechanics, query patterns, and idempotency.
API & Protocol Reference	Exhaustive REST endpoint contracts and STOMP topic/destination specifications.
Configuration Reference	Environment variables, YAML keys, agent JSON configs, and default values.
Failure Recovery & Resilience	Failure matrix, crash consistency boundaries, timeouts, and backoff policies.
Observability & Monitoring	Logging forensics, health checks, operational questions, and monitoring gaps.
Security & Vulnerability Audit	Threat modeling, BOLA vulnerability audit, and remediation guidance.
Performance & Scalability	CPU/memory profiles, database write capacity, and 1 to 10,000 node modeling.
Testing & Verification	Test suite inventory, gaps, and loadtester/ simulation harness analysis.
Operational Troubleshooting	Diagnostic symptom-resolution matrix and verification runbooks.
Architecture Decision Records	ADR-01 through ADR-05 reverse-engineered directly from source.

---

Actual System Architecture

flowchart LR
  subgraph UI[Dashboard UI - Next.js 16]
    Browser[Browser Client]
  end

  subgraph Backend[Spring Boot Backend]
    REST[REST API - /auth, /company, /devices, /agent]
    WS[STOMP WebSocket Broker - /ws]
    Auth[JWT Filter + WebSocketAuthInterceptor]
    Rate[RateLimitFilter - Exempts /agent & /ws]
    DB[(PostgreSQL 16 / TimescaleDB)]
    Scheduler[DeviceStatusScheduler - 30s Fixed Rate]
  end

  subgraph Agent[Monitor Agent - Go]
    MetricsLoop[Metrics WS Loop - Adaptive 1-5s]
    DetailLoop[Detail REST Loop - 30s Interval]
    CmdLoop[Command WS Loop - Shell/Service Control]
  end

  Browser -->|HTTPS JSON - Bearer JWT| REST
  Browser <-->|STOMP SockJS - /topic, /app| WS
  REST --> Auth
  REST --> Rate
  REST --> DB
  WS --> Auth
  WS --> DB
  Scheduler --> DB
  Scheduler -.->|Broadcast OFFLINE status| WS

  MetricsLoop <-->|STOMP SEND /app/agent/metrics-batch| WS
  CmdLoop <-->|STOMP SUB /topic/agent, SEND /app/command-result| WS
  DetailLoop -->|HTTP POST /agent/metrics-detail/batch (x-agent-token)| REST

Loading

---

Key Runtime Flows

sequenceDiagram
  autonumber
  participant UI as Dashboard UI
  participant API as Backend REST
  participant WS as Backend STOMP WS
  participant Agent as Monitor Agent

  UI->>API: POST /auth/login
  API-->>UI: JWT (HS256)
  Agent->>API: POST /agent/register (Body: token, hostname, ip, os)
  API-->>Agent: deviceId (UUID)
  Agent->>WS: CONNECT (Header: x-agent-token)
  WS-->>Agent: CONNECTED
  UI->>WS: CONNECT (Header: Authorization Bearer JWT)
  WS-->>UI: CONNECTED
  Agent->>WS: SEND /app/agent/metrics-batch (batch: 10 items or 5s)
  WS-->>UI: MESSAGE /topic/device/{deviceId} (Latest metric broadcast)
  UI->>WS: SEND /app/command/{deviceId} (Payload: shell/service)
  WS-->>Agent: MESSAGE /topic/agent/{deviceId}
  Agent->>Agent: Execute locally (powershell.exe / sh, 30s timeout)
  Agent->>WS: SEND /app/command-result (Chunked <= 12KB)
  WS-->>UI: MESSAGE /topic/command-result/{deviceId}

Loading

---

Repository Layout

• backend/ Spring Boot 4.0.2 REST + STOMP WebSocket API & TimescaleDB storage.
• frontend/ Next.js 16.1.6 dashboard with React 19 & Tailwind CSS v4.
• monitor-agent/ Go monitoring agent daemon and Cobra CLI suite.
• loadtester/ High-concurrency agent simulator and benchmarking suite.
• scripts/ Build, cross-compilation, version bump, and installation scripts.
• docs/ Definitive technical documentation suite.

---

Quick Start

1) Backend (Docker Compose with TimescaleDB)

cd backend
docker compose up --build

Or locally via Maven:

cd backend
./mvnw spring-boot:run

2) Frontend (Next.js Dashboard)

cd frontend
bun install
bun run dev

Dashboard will be accessible at http://localhost:3000.

3) Monitor Agent (Go)

cd monitor-agent
go build -o monitor-agent .
./monitor-agent install --token <YOUR_COMPANY_TOKEN> --server http://localhost:8080
./monitor-agent start

Or run directly in foreground for debugging:

./monitor-agent run

---

Screenshots

\n