# Overview

PearData is **decentralized, P2P, real-time host monitoring** for the Pear / Holepunch ecosystem.

## Three planes

| Plane | Role |
|-------|------|
| **Agent** (`peardata-server`) | Collects metrics (~1s), stores hot/warm history, scores anomalies, serves P2P RPC + local REST |
| **Desktop** (Pear / Electron) | Connects to one or more agents, shows Overview / Charts / Alerts / Fleet / Settings |
| **REST** (`127.0.0.1:18888`) | Agent-compatible HTTP for scripts, Grafana, Prometheus |

You dial agents by **public key** (viewer) or **`pd1.` invite** / admin seed for elevated roles.

## Desktop tabs

| Tab | Purpose |
|-----|---------|
| **Overview** | Compact home: KPIs + six spark panels + optional fleet strip |
| **Charts** | Full metrics wall — every catalog chart, shared time, investigation |
| **Alerts** | Recent anomaly / threshold events |
| **Logs** | Host journal (default for admins), anomalies, and audit trail with search / Follow |
| **Settings → Data** | Agent Data Manager — retention, auto-prune, disk usage (admin) |
| **Containers** | Docker charts with human names when the agent has socket access |
| **Fleet** | Saved + live agents; set active, reconnect, open Charts |
| **Connect** | Dial a new key or invite |
| **Settings** | Theme, notifications, history depth, reconnect |

## Investigation tools (don’t confuse them)

| Tool | Where | Job |
|------|-------|-----|
| **Correlate** | Charts toolbar | “What **changed** around this highlight vs baseline?” |
| **Related (⇢)** | Per chart card | “What charts are **related** to this one?” (context / Pearson) |
| **Board** | Charts toolbar | Show **pinned** charts only |
| **Force** | Charts toolbar | Keep live updates (wallboard) even if paused elsewhere |

See [Metric Correlations](./metric-correlations.md) and [Related metrics](./related-metrics.md).

## Persistence

Desktop state lives under `~/.config/peardata` (or `PEARDATA_HOME`):

- Saved peers / last active agent  
- Settings (theme, chart prefs, reconnect)  
- Metrics wall prefs (pins, card heights, chart types)

Agents restore on launch when **Restore saved agents** is enabled (Settings → Connections).