docs: add Mermaid diagrams to improve visual documentation

Enhance documentation with six Mermaid diagrams to better explain
complex system implementations:

- Adaptive polling lifecycle flowchart showing enqueue→execute→feedback
  cycle with scheduler, priority queue, and worker interactions
- Circuit breaker state machine diagram illustrating Closed↔Open↔Half-open
  transitions with triggers and recovery paths
- Temperature proxy architecture diagram highlighting trust boundaries,
  security controls, and data flow between host/container/cluster
- Sensor proxy request flow sequence diagram showing auth, rate limiting,
  validation, and SSH execution pipeline
- Alert webhook pipeline flowchart detailing template resolution, URL
  rendering, HTTP dispatch, and retry logic
- Script library workflow diagram illustrating dev→test→bundle→distribute
  lifecycle emphasizing modular design

These visualizations make it easier for operators and contributors to
understand Pulse's sophisticated architectural patterns.
This commit is contained in:
rcourtman 2025-10-21 10:40:33 +00:00
parent f9cb96ceb8
commit 85ffe10aed
13 changed files with 875 additions and 39 deletions

View file

@ -9,6 +9,41 @@
- Limiters: ~12 requests/minute per UID (burst 2), per-UID concurrency 2, global concurrency 8, 2s penalty on validation failures
## Monitoring Alerts & Response
```mermaid
sequenceDiagram
participant Backend as Pulse Backend
participant Proxy as Sensor Proxy RPC Server
participant Limiter as Limiter (per UID & global)
participant Validator as Payload Validator
participant SSH as Cluster Node (forced `sensors -j`)
participant Metrics as Metrics & Audit Log
Backend->>Proxy: RPC request (get_temperature)
Proxy->>Proxy: Extract SO_PEERCRED (UID/GID/PID)
Proxy->>Limiter: Check per-UID rate & concurrency
alt Rate limit exceeded
Limiter-->>Proxy: reject
Proxy-->>Backend: 429 Too Many Requests (2 s penalty)
Proxy->>Metrics: increment limiter_rejections_total
else Allowed
Limiter-->>Proxy: permit
Proxy->>Validator: Validate method & payload
alt Validation failure
Validator-->>Proxy: error
Proxy-->>Backend: 400 validation error
Proxy->>Metrics: penalty + audit log entry
else Valid request
Validator-->>Proxy: ok
Proxy->>SSH: run `sensors -j` via forced command
SSH-->>Proxy: temperature JSON
Proxy-->>Backend: telemetry payload
Proxy->>Metrics: record success, latency histogram
Proxy->>Metrics: append audit/audit trail
end
end
```
### Rate Limit Hits (`pulse_proxy_limiter_rejections_total`)
1. Check audit log entries tagged `limiter.rejection` for offending UID.
2. Confirm workload legitimacy; if expected, consider increasing limits via config override.