# Telemetry Service Specification

## Overview
YA-WAMF includes an optional telemetry service to collect anonymous usage statistics. **Telemetry is disabled by default** and requires explicit opt-in.

## Why Telemetry?
As a solo developer working on this project, telemetry helps me understand if YA-WAMF is solving real problems for the broader bird enthusiast community, or if I'm primarily building for my own use case. Knowing that others find value in this work helps validate the time investment and guides development priorities - it's encouraging to know you're not building in isolation.

Additionally, the data helps to:
- Identify popular hardware platforms to prioritize optimization
- Understand which AI models are most commonly used
- Monitor version adoption rates to ensure users are on stable builds

## Data Collection Policy

### What is Collected?
The heartbeat payload is strictly limited to metadata about the installation and environment:
- **Installation ID**: A random UUID generated once per installation. It is not linked to any personal identity.
- **Application Version**: The current version/build of YA-WAMF.
- **Platform Metadata**: Operating system type, release version, and machine architecture (e.g., Linux x86_64).
- **Configuration Flags**: Enabled features such as LLM providers, Media Caching, and Auto Video Classification.
- **Feature Usage**: Which integrations (eBird, iNaturalist), notification channels (Discord, Email, etc.), and enrichment modes are active.
- **Access Settings**: Whether authentication or public access is enabled (boolean flags only).
- **Geography**: The approximate country derived from the Cloudflare request header (the IP address itself is **not** stored in the database).

### What is NOT Collected?
- **No Private Data**: No audio recordings, video clips, or snapshots are ever sent.
- **No User Content**: No bird detection transcripts, species names, or scientific data are collected.
- **No PII**: No names, email addresses, IP addresses, usernames, tokens, or precise locations are stored.

## Technical Details

### Endpoint
- **URL**: `https://yawamf-telemetry.ya-wamf.workers.dev/heartbeat`
- **Frequency**: Once every 24 hours while the application is running.

### Payload Schema
```json
{
  "installation_id": "string (UUID)",
  "version": "string (e.g. 2.0.0)",
  "platform": {
    "system": "string (e.g. Linux)",
    "release": "string",
    "machine": "string"
  },
  "configuration": {
    "model_type": "string",
    "llm_enabled": "boolean",
    "llm_provider": "string",
    "media_cache_enabled": "boolean",
    "media_cache_clips": "boolean",
    "auto_video_classification": "boolean"
  },
  "integrations": {
    "birdnet_enabled": "boolean",
    "birdweather_enabled": "boolean",
    "ebird_enabled": "boolean",
    "inaturalist_enabled": "boolean"
  },
  "notifications": {
    "discord_enabled": "boolean",
    "pushover_enabled": "boolean",
    "telegram_enabled": "boolean",
    "email_enabled": "boolean",
    "mode": "string"
  },
  "enrichment": {
    "mode": "string",
    "summary_source": "string",
    "sightings_source": "string",
    "taxonomy_source": "string"
  },
  "access": {
    "auth_enabled": "boolean",
    "public_access_enabled": "boolean"
  }
}
```

## User Control (Opt-In)
Telemetry is **disabled by default** and completely optional. Users who wish to help improve YA-WAMF can opt in at any time via the **Settings > Connections > Telemetry** toggle in the UI. You can also disable it at any time if you change your mind.

On first launch, you may see a friendly banner inviting you to opt in - this can be dismissed and won't appear again.

## Source Code & Transparency
I believe in full transparency regarding the data I collect. You can inspect exactly how the heartbeat is constructed and transmitted in the backend source code:

- **[Telemetry Service (Backend)](../backend/app/services/telemetry_service.py)**: This module handles the generation of the anonymous Installation ID, gathers the metadata defined above, and transmits the payload via HTTPS.
- **[Telemetry Worker (Receiver)](../apps/telemetry-worker/)**: The source code for the Cloudflare Worker that receives and stores the data is available in the repository.