Phase 8 — Product analytics and external integrations

[b5463]

Part of Milestone E — Intelligence and Launch. Ref: #27

Allow managed and external products to report health, releases, errors, events and usage.

---

Alex tasks

Tables

• integration_keys
• integration_key_events
• product_events
• product_metric_hourly
• product_metric_daily
• error_groups
• release_reports
• external_heartbeats

Integration key scopes

• heartbeat:write
• events:write
• errors:write
• releases:write
• metrics:write
• entitlements:check
• licences:validate

Ingestion endpoints

• POST /api/ingest/heartbeat
• POST /api/ingest/releases
• POST /api/ingest/errors
• POST /api/ingest/events
• POST /api/ingest/metrics

Aggregation jobs (do not query raw events for dashboard cards)

• analytics.aggregate.hourly
• analytics.aggregate.daily
• analytics.compact.raw
• analytics.retention.cleanup

Safety

Analytics must never block: Stripe webhooks, entitlement checks, licence validation, admin login, deploy rollback.

• Rate-limiting and payload size caps on ingestion endpoints

Tests

• Bad integration key rejected
• Scoped key cannot access wrong endpoint
• Event payload size capped
• Heartbeat updates external system health
• Release report appears in dashboard
• Analytics aggregation creates daily metrics
• High event volume is rate-limited
• Analytics failure does not affect entitlement checks

---

Tomas tasks

• Integration key management UI (create, rotate, revoke, scope display)
• Analytics dashboard — product metrics (separated from operational)
• Analytics dashboard — operational metrics
• Error groups UI
• Release reports UI
• External system health display
• Event volume monitoring display

---

Exit gate

• External test app can report heartbeat
• Managed app can send events
• Dashboard shows product analytics from aggregates (not raw events)
• Integration keys can be rotated and revoked

Rollback

Disable ingestion endpoints. Existing infra stats unaffected.