# PearData

**Decentralized, P2P, real-time monitoring for the Pear / Holepunch ecosystem.**

Each machine runs a lightweight **PearMonitor agent**. A Pear desktop client dials agents by public key and shows fleet + per-node live dashboards. Agents also expose an **agent-compatible REST API** (`/api/v1`, `/api/v2`, `/api/v3`) for scripts, Grafana, and Prometheus.

Built from the [pear-app-template](https://github.com/snxraven) HyperDHT + protomux-rpc patterns used by PearDock-class apps.

| Plane | Stack |
|-------|--------|
| Transport | **HyperDHT** secret streams (Noise) |
| RPC | **protomux-rpc** + compact-encoding JSON |
| Metrics | 1s collector → tiered buffers → push + query |
| AuthZ | Roles (`viewer` / `operator` / `admin`) + `pd1.` invites + admin seed |
| HTTP | agent-style REST on `127.0.0.1:18888` |
| Desktop | **Pear** (`pear-electron` + `pear-bridge` + `<pear-ctrl>`) |

---

## Quick start

### One-line installer (recommended)

```bash
curl -fsSL https://git.ssh.surf/snxraven/peardata/raw/branch/main/scripts/install.sh | bash
```

```bash
# Server only (Linux Bare + systemd → /opt/peardata)
# Enables journal Logs + Docker metrics/names when Docker is detected
curl -fsSL https://git.ssh.surf/snxraven/peardata/raw/branch/main/scripts/install.sh | bash -s -- --server --yes

# Desktop client only
curl -fsSL https://git.ssh.surf/snxraven/peardata/raw/branch/main/scripts/install.sh | bash -s -- --client --yes
```

### From source

```bash
cd peardata
npm install

# Terminal A — agent (prints public key + REST URL)
npm run start:server

# Terminal B — REST smoke test
curl -s http://127.0.0.1:18888/api/v3/info | jq
curl -s 'http://127.0.0.1:18888/api/v3/data?chart=system.cpu&after=-30&points=30' | jq

# Terminal C — mint an operator invite (optional)
npm run mint-invite -- operator

# Terminal D — Pear / Electron desktop
npm start
# or: npm run start:client
```

In the UI, paste the **agent public key** (viewer) or a **`pd1.` invite**.  
Paste `SERVER_SEED` for admin without an invite.

```bash
npm test
npm run healthcheck
```

---

## Repository layout

```
peardata/
├── app.js / index.html / ui/   # Pear fleet dashboard
├── shared/                     # Protocol, metrics catalog, schema, crypto
├── spec/                       # Generated Hyperschema + HyperDB definitions
├── scripts/build-db.js         # Regenerate spec/ (`npm run build:db`)
├── server/                     # PearMonitor agent
│   ├── server.js               # DHT + HyperDB + pipeline + REST boot
│   ├── pipeline.js             # collector → store → anomaly → push
│   ├── db/                     # HyperDB model + Corestore + swarm replicate
│   ├── handlers/monitor.js     # Domain RPCs
│   ├── services/               # collector, store, retention, warm-flush, anomaly, jobs
│   ├── rest/                   # agent-compatible HTTP API
│   └── core/ rpc/ utils/       # Auth, ACL, sessions (template)
├── client/                     # Multi-peer connection manager
├── user-guide/                 # End-user desktop workflows
├── docs/                       # Engineer / operator documentation
├── deploy/peardata.service     # systemd (installer also writes journal/docker groups)
└── test/
```

---

## npm scripts

| Script | Purpose |
|--------|---------|
| `npm start` | Pear desktop UI |
| `npm run start:server` | PearMonitor agent (P2P + REST) |
| `npm run start:client` | Electron desktop (packaged UI) |
| `npm run make` | Build Linux servers + all client arches |
| `npm run make:server` | Bare `peardata-server` (`linux-x64` / `linux-arm64`) |
| `npm run make:client` | Electron clients (all 64-bit hosts) |
| `npm test` | brittle unit + integration |
| `npm run mint-invite -- [role]` | Offline `pd1.` invite |
| `npm run build:db` | Regenerate HyperDB `spec/` |
| `npm run healthcheck` | Liveness / remote ping |
| `npm run soak` | Load exercise |

---

## Auth model

| Mode | How | Role |
|------|-----|------|
| Viewer | Dial public key only | `viewer` (read + subscribe) |
| Capability | `pd1.` invite or HMAC token | granted role |
| Admin seed | HMAC proof from `SERVER_SEED` | `admin` |
| Allowlist | `PEARDATA_ADMIN_KEYS` | admin for listed peers |

---

## Documentation

| Doc | Contents |
|-----|----------|
| **[User guide](./user-guide/README.md)** | Desktop — Charts, Correlations, Logs, Containers, Fleet, Settings / Data Manager |
| [Getting started](./docs/GETTING-STARTED.md) | Install, agent, REST, desktop, systemd (journal + Docker) |
| [Docs index](./docs/README.md) | Full engineer / operator doc set |
| [Roadmap](./docs/ROADMAP.md) | MVP → advanced phases |
| [Architecture](./docs/ARCHITECTURE.md) | PearDock mapping, planes, modules |
| [Protocol](./docs/PROTOCOL.md) | RPC methods & pushes (incl. Data Manager) |
| [Data model](./docs/DATA-MODEL.md) | Metrics, anomalies, health, weights, logs, retention tiers |
| [REST API](./docs/REST-API.md) | `/api/v1\|v2\|v3` |
| [Dashboard](./docs/DASHBOARD.md) | Charts wall / Correlate / Containers naming |
| [Tech choices](./docs/TECH-CHOICES.md) | Collector, charts, Bare maps |
| [HyperDB storage](./docs/STORAGE-HYPERDB.md) | Warm history, peer links, swarm sync, prune |
| [Release](./docs/RELEASE.md) | Binary host matrix + rolling CI |
| [CI](./docs/CI.md) | Gitea / GitHub pipelines |
| [Security](./docs/SECURITY.md) | Threat model & hardening |
| [Configuration](./docs/CONFIGURATION.md) | Environment reference |

---

## License

**AGPL-3.0-only** — see [LICENSE](./LICENSE).

PearData is released under the same license family as PearDock (GNU Affero General Public License v3).