danvics/Pulse
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Fix inaccurate architecture documentation

Browse source 
- Correct connection methods: Pulse uses REST APIs for PVE/PBS (not SSH)
- Update diagram to show HTTPS API connections on ports 8006/8007
- Add agent push model for Docker/Host metrics collection
- Remove incorrect SSH connection pooling references
- Update data flow to reflect API polling and agent push
This commit is contained in:
rcourtman 2025-12-02 23:32:14 +00:00
parent 8fca8c6eb4
commit 5c502d0c5f
1 changed files with 22 additions and 14 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

36
ARCHITECTURE.md
View file

@ -1,26 +1,27 @@
# Pulse Architecture # Pulse Architecture
Pulse is a real-time, agentless (mostly) monitoring system designed for Proxmox VE, Proxmox Backup Server, and Docker infrastructure. It is built with a **Go** backend and a **SolidJS** frontend, focusing on low latency, high concurrency, and a premium user experience. Pulse is a real-time monitoring system designed for Proxmox VE, Proxmox Backup Server, and Docker/Host infrastructure. It is built with a **Go** backend and a **SolidJS** frontend, focusing on low latency, high concurrency, and a premium user experience.
## 🏗 High-Level Overview ## 🏗 High-Level Overview
The system operates as a single binary that serves both the API and the static frontend assets. It connects to infrastructure nodes via SSH (for Proxmox) or local/remote Docker sockets to gather metrics, which are then streamed to connected clients via WebSockets. The system operates as a single binary that serves both the API and the static frontend assets. It connects to Proxmox infrastructure via their REST APIs (using API tokens or password auth), while Docker/Host metrics are collected by lightweight agents that push data to Pulse.
```mermaid ```mermaid
graph TD graph TD
User[User Browser] <-->|WebSocket / HTTP| Pulse[Pulse Server] User[User Browser] <-->|WebSocket / HTTP| Pulse[Pulse Server]
subgraph "Pulse Server (Go)" subgraph "Pulse Server (Go)"
API[REST API] API[REST API]
WS[WebSocket Hub] WS[WebSocket Hub]
Monitor[Monitoring Engine] Monitor[Monitoring Engine]
Config[Config Manager] Config[Config Manager]
end end
Pulse -->|SSH| PVE[Proxmox VE Node] Pulse -->|HTTPS API :8006| PVE[Proxmox VE Node]
Pulse -->|SSH| PBS[Proxmox Backup Server] Pulse -->|HTTPS API :8007| PBS[Proxmox Backup Server]
Pulse -->|Docker Socket| Docker[Docker Host] Agent[Pulse Agent] -->|HTTPS POST| API
Agent -.->|Collects from| DockerHost[Docker / Host]
Monitor --> WS Monitor --> WS
Monitor --> API Monitor --> API
``` ```
@ -37,23 +38,30 @@ The backend is a high-performance Go application designed for concurrent monitor
* Launches the HTTP server and WebSocket hub. * Launches the HTTP server and WebSocket hub.
2. **Monitoring Engine (`internal/monitoring`)**: 2. **Monitoring Engine (`internal/monitoring`)**:
* **Polymorphic Monitors**: Uses interfaces to treat PVE, PBS, and Docker hosts uniformly where possible. * **Polymorphic Monitors**: Uses interfaces to treat PVE and PBS hosts uniformly where possible.
* **Goroutines**: Each host is monitored in its own lightweight goroutine to ensure non-blocking operations. * **Goroutines**: Each host is monitored in its own lightweight goroutine to ensure non-blocking operations.
* **SSH Connection Pooling**: Maintains persistent SSH connections to Proxmox nodes to avoid handshake overhead during metric collection. * **API Clients**: Communicates with Proxmox VE/PBS via their REST APIs using API tokens or password-based tickets.
3. **WebSocket Hub (`internal/websocket`)**: 3. **Agent Receivers (`internal/api/agents`)**:
* Receives metrics from `pulse-agent` instances via HTTP POST.
* Agents collect Docker container stats, host metrics, and temperatures locally.
* Push-based model: agents initiate connections to Pulse, not vice versa.
4. **WebSocket Hub (`internal/websocket`)**:
* Manages active client connections. * Manages active client connections.
* Broadcasts metric updates in real-time. * Broadcasts metric updates in real-time.
* Handles "commands" from the frontend (e.g., requesting immediate updates). * Handles "commands" from the frontend (e.g., requesting immediate updates).
4. **API Layer (`internal/api`)**: 5. **API Layer (`internal/api`)**:
* RESTful endpoints for configuration (adding nodes, setting thresholds). * RESTful endpoints for configuration (adding nodes, setting thresholds).
* Handles authentication and secure token management. * Handles authentication and secure token management.
### Data Flow ### Data Flow
1. **Collection**: The `Monitoring Engine` ticks (default: 2s). It executes commands on remote hosts (e.g., `pvesh`, `docker stats`). 1. **Collection**:
2. **Normalization**: Raw JSON/Text output is parsed into standardized Go structs (`HostMetrics`, `ContainerMetrics`). * **Proxmox**: The Monitoring Engine polls PVE/PBS REST APIs (default: 2s interval).
* **Agents**: Docker/Host agents push metrics to Pulse at their configured interval (default: 30s).
2. **Normalization**: API responses and agent reports are parsed into standardized Go structs (`HostMetrics`, `ContainerMetrics`).
3. **Broadcast**: Normalized data is sent to the `WebSocket Hub`. 3. **Broadcast**: Normalized data is sent to the `WebSocket Hub`.
4. **Delivery**: The Hub serializes the data to JSON and pushes it to all subscribed frontend clients. 4. **Delivery**: The Hub serializes the data to JSON and pushes it to all subscribed frontend clients.