---
schema: foundry-doc-v1
title: "Telemetry architecture"
slug: telemetry-architecture
short_description: "The platform collects web traffic analytics from production edge nodes and routes them to a locally controlled processing environment through an encrypted path without passing through third-party cloud services."
category: infrastructure
type: topic
content_type: topic
quality: complete
status: active
bcsc_class: public-disclosure-safe
last_edited: 2026-05-09
editor: pointsav-engineering
paired_with: telemetry-architecture.es.md
---

The platform's telemetry system collects web traffic analytics from production [[edge-deployment|edge nodes]] and routes them to a local processing environment over the [[sovereign-mesh|WireGuard mesh]] without passing through a third-party cloud aggregation service. All analysis runs on hardware the operator controls, consistent with [[customer-hostability|customer-rooted data custody]].

This article describes the architecture as of the initial deployment. The routing topology and processing stack are planned to evolve as the fleet expands.

## Key Takeaways

- Telemetry routes through four tiers: edge capture → WireGuard encrypted transit → local processing node → control workstation pull. No payload passes through a third-party cloud aggregation service at any step.
- Per-tenant isolation is enforced at the ledger level. Each tenant's analytics are written to separate CSV ledgers on the local processing node and are never commingled in a shared cloud table.
- The control workstation pulls only compiled Markdown reports — not the raw CSV ledger. Raw data stays on the local processing node; what moves to the analyst is the extracted summary. This design limits the blast radius of a workstation compromise to summary data, not the full traffic record.
- Local-first telemetry is a precondition of the tenancy isolation model and the [[customer-hostability|customer-rooted data custody]] property. The operator holds full custody of traffic analytics; no third party holds or processes the raw data.

## Four-tier routing path

### Tier 1 — Edge capture

Live Nginx relays on the cloud edge nodes capture JSON payloads from organic web traffic and route them to the local network over designated ports: `10.50.0.2:8081` for the PointSav tenant and `10.50.0.2:8082` for the Woodfine tenant. The relays do not inspect or buffer payloads; they forward them directly to the tunnel endpoint.

### Tier 2 — Encrypted transit

Payloads traverse a WireGuard mesh (`wg0`) between the cloud edge and the local processing node. The tunnel terminates at the local firewall. Payloads are encrypted in transit and do not pass through any intermediate cloud service.

### Tier 3 — Local processing

A Rust telemetry daemon running on the local processing node (`laptop-a`) binds to all interfaces, receives the decrypted payloads, and writes them to per-tenant CSV ledgers. A cross-reference process consults the GeoLite2 City database to resolve IP addresses to geographic regions and produces structured Markdown reports from the ledger data.

### Tier 4 — Analysis extraction

The control node (the operator's workstation) runs a pull script (`pull_sovereign_telemetry.sh`) that physically extracts the compiled reports from the processing node without touching the raw ledger data. Analysis is performed on the extracted reports; the raw CSV ledger remains on the processing node.

## Design rationale

Routing telemetry to a locally controlled node rather than a cloud aggregation service means the operator retains full custody of traffic data. No third party holds or processes the raw analytics. This is a precondition for the tenancy isolation model: each tenant's analytics are isolated at the ledger level and never commingled in a shared cloud table.

## See also

- [[worm-ledger-architecture]] — the WORM ledger design that shares the append-only write model
- [[edge-deployment]] — the boundary ingest architecture for the Ring 1 services
- [[compounding-substrate]] — the broader substrate context for local-first data custody