peardata/docs/TECH-CHOICES.md

Tech choices

Recommendations for collection, streaming, visualization, and reusable libraries.

Transport & identity

Choice	Why
HyperDHT	Same peer identity + hole-punching model as PearDock
protomux-rpc	Multiplexed request/response + server push events
compact-encoding JSON	Fast enough for control + 1s metric batches; shared with template
Ed25519 seeds	Agent address = pubkey; admin proof via HMAC from seed

Streaming metrics

MVP uses protomux-rpc event pushes (push:metrics) with per-session subscribe + throttle.

If fleet scale demands it later:

1. Dedicated protomux channel with binary packs (Float64 arrays)
2. Hypercore / Hyperbee for durable streams a parent can replicate
3. Extract a shared pearrpc package (session middleware + hot-path helpers) from this template

For MVP, JSON pushes keep the stack simple and debuggable.

Bare / Pear runtime (no Node builtins)

Pear’s native runtime is Bare. Do not rely on Node core modules existing at runtime.

Pattern	Use
package.json imports map	fs / os / path / crypto / events / http / … → bare-* under "bare" condition (same idea as PearDock / pear-docs node-compat)
bare-node-runtime/global	Loaded first in Bare entrypoints (bin/peardata-server.mjs, index.js) for process / Buffer / fetch
b4a	Buffers in shared/ and wire code (prefer over Node Buffer)
Direct bare-*	Optional for new Bare-first modules

Keep bare-safe: shared/, client/, Pear app.js / index.js / ui/.
Agent (server/): may keep Node-style import names; under Bare they resolve via the imports map. Boot via bin/peardata-server.mjs.

Do not use if (isBare) require('bare-fs') else require('fs') branches for packable apps — Bare’s packer walks both sides. Prefer import maps.

Collection

Option	Verdict
os + /proc via bare-os / bare-fs (chosen)	Hybrid Node+Bare; low overhead
node-os-utils	Convenient but extra dep / less control
Native bindings (systeminformation, etc.)	Higher fidelity; consider Phase 2 for Windows depth
Shell out to vmstat/iostat	Avoid on hot path

Linux: /proc/meminfo, /proc/loadavg, /proc/net/dev, /proc/diskstats
macOS/Windows: os fallbacks (CPU%, freemem, loadavg where available); I/O/net rates may be zero until platform collectors land.

Target overhead: single timer, no child processes per tick, ring buffers only.

Storage

Tier	Implementation
Hot	In-memory ring (server/services/store.js)
Warm	HyperDB + Corestore (+ optional Hyperswarm) — see STORAGE-HYPERDB.md
Policy	Data Manager (retention.json, default 1y warm age, auto-prune) — server/services/retention.js
HA / multi-writer parents	Autobase with HyperDB view (extension: false)
Avoid	SQLite as primary P2P store; copying corestore folders as “backup”

HyperDB engines

Engine	Sync	Use
HyperDB.bee(core, spec)	P2P via Hypercore	Agent meta + warm history + linked peers
HyperDB.rocks(path, spec)	Local only	Fast local index / desktop cache (pear-hyperdb style)

Visualization (desktop)

Option	Verdict
Canvas sparklines (chosen MVP)	No extra deps inside Pear; snappy for 1s updates
uPlot	Best next step for interactive charts (tiny, fast)
Chart.js / ECharts	Heavier; fine for secondary views
Grafana via REST	External; use /api/v3/data + Prometheus export

REST

http module (no Express) — under Bare this is bare-http1 via import maps. Small attack surface for agent-style GET APIs. Default bind 127.0.0.1:18888 (PEARDATA_REST_PORT).

Packaging

Piece	Approach
Agent	Node 20+ or Bare (bin/peardata-server.mjs), systemd unit deploy/peardata.service
Desktop	Pear (pear-electron + pear-bridge) with Bare-ready imports
Invites	pd1. tokens (PearDock-style)
Installer	scripts/install.sh (rolling binaries; journal + Docker socket when detected; see RELEASE.md)

Reusable library extraction (recommended later)

From this codebase / PearDock patterns:

Package	Contents
@pear/rpc-session or pearrpc	PeerSession middleware, ACL, rate limit, audit hooks
pear-metrics-wire	Context/chart catalog types + query args
pear-invite	pd1. encode/decode + capability HMAC

PearData is AGPL-3.0-only (same family as PearDock). Prefer composing via public APIs rather than vendoring third-party AGPL trees wholesale unless intentionally unifying under AGPL.

Integration seams

Ecosystem	Seam
PearDock	Container chart plugin reading dock RPC
PearVirt	VM CPU/mem contexts
HoneyPeer	Optional agent directory announcements
BareOS	Bare-compatible collector build
Holesail	Tunnel REST or future agent web UI