vouchfx-telemetry-backend¶

The server half of vouchfx's opt-in, privacy-first telemetry system.

Status (post-pilot, 2026-07): self-host reference — no maintainer-hosted instance is planned. The pilot programme this backend was built for has been discontinued; the code is complete, tested and kept as the reference implementation of the frozen /v1/telemetry wire contract. The engine-side transport ships in the vouchfx engine and stays inert until an endpoint and token are configured, so engine telemetry remains local-only unless you deploy this backend yourself (self-hosting guide, or the retained Azure/Bicep deployment). The coverage badge measures the unit-testable surface; the PostgreSQL persistence and background-maintenance layers are covered separately by the Testcontainers integration suite.

What it is¶

A lean ASP.NET Core 8 minimal-API service that:

1. Ingests the opt-in JSON Lines telemetry batches the vouchfx engine already produces (POST /v1/telemetry), authenticated with a shared Bearer token, and stores them in PostgreSQL under a 90-day retention policy.
2. Honours an install-id deletion request (POST /v1/telemetry/forget) within 30 days.
3. Self-maintains via a daily in-service job: partition pre-create, 90-day partition drop, and forget-queue drain.

It is privacy-allowlist-only by construction: it stores only the frozen TelemetryEvent fields (aggregate counts, timings, anonymous install id, versions). Nothing a customer's tests touch can reach it — there is nowhere to put it.

Documentation¶

• Why telemetry & how to opt in — User-facing overview: what telemetry collects, how to enable/disable, and your privacy rights
• Self-hosting without Azure — Building and running the backend on your own infrastructure
• Wire Contract — The HTTP API specification (endpoints, status codes, payload schema, deduplication)
• Architecture — System design, five-component architecture, PostgreSQL schema, Azure topology
• Operations Runbook — Deployment procedures, configuration reference, troubleshooting, maintenance tasks
• Privacy Policy — Data handling, retention, deletion, and compliance considerations
• Engine telemetry reference — CLI-side telemetry configuration in the vouchfx engine

Endpoints at a Glance¶

Repository layout¶

src/                 the ASP.NET Core service
tests/               unit tests (no DB) + Testcontainers Postgres integration tests
deploy/              Bicep IaC, Dockerfile inputs, bootstrap.sql
docs/                architecture, operations runbook, privacy, wire-contract
.github/workflows/   CI (build/format/unit), integration, deploy

Build & test¶

dotnet build Vouchfx.Telemetry.Backend.sln
dotnet test tests/Vouchfx.Telemetry.Backend.UnitTests        # no Docker required
dotnet test tests/Vouchfx.Telemetry.Backend.IntegrationTests # requires Docker (Testcontainers)

Contributing & security¶

Contributions are welcome — see CONTRIBUTING.md for the build, test, and quality gates, and the CODE_OF_CONDUCT.md that applies to all interactions here. To report a suspected vulnerability, please use GitHub private vulnerability reporting as described in SECURITY.md — never a public issue. Product-level telemetry discussion belongs in the engine repository's issues.

Licence¶

Apache-2.0 (matching the vouchfx engine).