┌─────────────────────────────────────────────────────┐
│ Analysis Summary                                    │
├─────────────────────────────────────────────────────┤
│ Type: Project                                       │
│ Primary Language: go + typescript + markdown        │
│ LOC: 85K                                            │
│ Test Files: 13                                      │
│ Architecture: go                                    │
│ Confidence: High                                    │
└─────────────────────────────────────────────────────┘

Analyzed: 0c832a63 from 2025-10-03

Pulse: Real-time Infrastructure Monitoring for Proxmox Environments

Pulse is a Go-based monitoring solution specifically designed for Proxmox Virtual Environment (PVE) and Proxmox Backup Server (PBS) infrastructure. The project combines a Go backend with a TypeScript frontend to provide real-time monitoring, alerting, and management capabilities for virtualized environments.

What Pulse Does

Based on the repository analysis, Pulse serves as a centralized monitoring dashboard for Proxmox infrastructure. The README indicates it provides “real-time monitoring for Proxmox VE and PBS with alerts and webhooks” and can “monitor your entire Proxmox infrastructure from a single dashboard.”

The system offers several key capabilities:

• Auto-discovery of Proxmox nodes on the network
• Live monitoring of VMs, containers, nodes, and storage
• Smart alerts via email and webhooks (Discord, Slack, Telegram, Teams)
• Unified view of PBS backups, PVE backups, and snapshots
• Configuration export/import with encryption

Architecture and Implementation

The codebase spans 85,112 lines across 249 files, with Go comprising 42,372 lines and TypeScript contributing 32,131 lines. This roughly even split suggests a substantial frontend application paired with a comprehensive backend service.

WebSocket-Based Real-time Updates

The Go backend implements WebSocket functionality for real-time updates. The hub concurrency test (internal/websocket/hub_concurrency_test.go:9-28) demonstrates the WebSocket hub handling concurrent client connections:

func TestHubConcurrentClients(t *testing.T) {
	hub := NewHub(nil)

	// Start hub processing loop in background
	go hub.Run()

	const iterations = 200

	var wg sync.WaitGroup
	wg.Add(3)

	// Simulate register/unregister from multiple goroutines
	go func() {
		defer wg.Done()
		for i := 0; i < iterations; i++ {
			client := &Client{
				hub:  hub,
				send: make(chan []byte, 10),
				id:   "client-register-" + string(rune(i)),
			}

The concurrent mutation test (internal/websocket/concurrency_test.go:12-31) shows the system handles concurrent alert broadcasting safely with proper goroutine coordination.

Frontend Search and Filtering

The TypeScript frontend implements sophisticated search functionality. The search query parser (frontend-modern/src/utils/searchQuery.ts:50-64) handles metric-based filtering:

export function parseFilter(term: string): ParsedFilter {
  term = term.trim();

  // Try to parse metric condition (e.g., "cpu>80", "size>1000000000")
  const metricMatch = term.match(/^(\w+)\s*(>|<|>=|<=|=|==)\s*(\d+(?:\.\d+)?)$/i);
  if (metricMatch) {
    const [, field, operator, value] = metricMatch;
    const parsedValue = parseFloat(value);
    if (isNaN(parsedValue)) {
      return {
        type: 'raw',
        rawText: term,
      };
    }

The system supports complex queries with AND/OR operators, as shown in the filter stack parser (frontend-modern/src/utils/searchQuery.ts:92-106).

Tag Color System

The frontend includes a deterministic tag coloring system (frontend-modern/src/utils/tagColors.ts:8-22) that ensures consistent visual representation:

function hashString(str: string): number {
  let hash = 0;
  for (let i = 0; i < str.length; i++) {
    const char = str.charCodeAt(i);
    hash = (hash << 5) - hash + char;
    hash = hash & hash; // Convert to 32bit integer
  }
  return Math.abs(hash);
}

The color generation function (frontend-modern/src/utils/tagColors.ts:22-36) uses HSL color space for consistent saturation and lightness across different tags.

Real Usage Patterns

The analysis found 13 test files demonstrating various usage patterns. The WebSocket tests show the system handling 200 concurrent iterations of client registration and unregistration, indicating the system is designed for high-concurrency scenarios.

The README provides extensive Docker deployment examples, suggesting containerized deployment is a primary use case. The Docker Compose configuration includes comprehensive environment variable options for security, performance, and CORS settings.

Alternative Approaches

Pulse differentiates itself by focusing specifically on Proxmox environments with built-in auto-discovery and one-liner setup scripts, whereas general-purpose monitoring solutions require extensive configuration for virtualization platforms.

Performance Characteristics

Bundle Impact:

• Total codebase: 85,112 lines across 249 files
• Go backend: 42,372 lines
• TypeScript frontend: 32,131 lines
• Minimal dependencies: only 10 Go dependencies

Runtime Dependencies: The Go backend uses lightweight dependencies including gorilla/websocket for WebSocket support, zerolog for logging, and standard OAuth2 libraries. The minimal dependency count (10 total) suggests a focus on reducing external dependencies.

Resource Usage: The README emphasizes “minimal resource usage” as a design goal, with the Go backend providing efficiency advantages over interpreted language alternatives.

Best for: Organizations running Proxmox infrastructure who need dedicated monitoring without the complexity of general-purpose monitoring stacks.

Dependencies and Ecosystem

The dependency analysis reveals a focused approach with 10 carefully selected Go modules:

• github.com/gorilla/websocket for real-time communication
• github.com/rs/zerolog for structured logging
• github.com/spf13/cobra for CLI functionality
• OAuth2 and OIDC libraries for authentication
• Standard crypto and file watching utilities

This minimal dependency footprint reduces security surface area and maintenance overhead compared to monitoring solutions with extensive dependency trees.

Code Quality Observations

The codebase demonstrates several quality indicators:

1. Comprehensive Testing: 13 test files with concurrent operation testing show attention to reliability under load
2. Security Focus: The README extensively documents security features including credential encryption, CSRF protection, and rate limiting
3. Type Safety: The TypeScript frontend uses proper typing, as evidenced in the search query interfaces and tag color functions
4. Error Handling: The search parser includes proper validation and fallback logic for malformed input

The hash-based tag coloring system shows thoughtful UX design, ensuring visual consistency across sessions while maintaining good contrast ratios.

When to Use Pulse

The evidence suggests Pulse is well-suited for:

• Organizations with existing Proxmox VE/PBS infrastructure
• Environments requiring real-time monitoring with WebSocket updates
• Deployments where minimal resource usage is important
• Scenarios needing integrated backup monitoring across PVE and PBS

The system appears less suitable for:

• Mixed virtualization environments (VMware, Hyper-V, etc.)
• Organizations requiring extensive customization beyond Proxmox monitoring
• Environments where general-purpose monitoring tools are already established

The auto-discovery features and Proxmox-specific integration make it particularly valuable for homogeneous Proxmox environments where setup simplicity is prioritized over broad platform support.