PMF Metrics & Churn Management

Relevant source files

The following files were used as context for generating this wiki page:

• src/lib/pmf/metrics.ts
• src/lib/pmf/service.ts
• src/app/dashboard/pmf/page.tsx
• supabase/migrations/0016_pmf_validation.sql
• src/tests/pmf-metrics.test.ts

The PMF (Product-Market Fit) Metrics & Churn Management system is a comprehensive toolset designed to capture, aggregate, and visualize user satisfaction and retention data. It enables the Comply-Quick team to monitor Net Promoter Scores (NPS), analyze reasons for subscription cancellations (churn), and track the overall subscription funnel performance.

This system is built on a DB-backed service layer that gates administrative views behind a specific allowlist while allowing authenticated users to submit feedback through Row Level Security (RLS) protected tables. The architecture separates pure mathematical computation from database interactions, ensuring high testability and reliable data reporting.
Sources: src/lib/pmf/service.ts:1-9, src/lib/pmf/metrics.ts:1-5

Data Architecture and Storage

The system utilizes two primary capture tables and leverages existing subscription data to generate metrics. Data is often segmented by acquisition channel (e.g., organic, ads, affiliate) to provide granular insights into different user cohorts.

Database Schema

The diagram shows the relationship between feedback tables and the central user/subscription entities.
Sources: supabase/migrations/0016_pmf_validation.sql:19-53, src/lib/pmf/service.ts:103-105

Table	Field	Type	Constraints	Description
nps_responses	score	smallint	0-10	Raw NPS score from user
nps_responses	channel	text	-	Acquisition source (ads, organic, etc.)
churn_surveys	reason	text	Enum check	Predefined cancellation reason
churn_surveys	comment	text	Max 2000 chars	Optional user feedback
Sources: supabase/migrations/0016_pmf_validation.sql:20-43, src/lib/pmf/service.ts:36, 61

Metric Computation Logic

The system utilizes pure, dependency-free helper functions to process raw data into actionable metrics. This ensures that calculations for NPS and retention rates are consistent across the application.

Net Promoter Score (NPS)

NPS is calculated by categorizing scores into three buckets:

• Promoters: Scores 9–10
• Passives: Scores 7–8
• Detractors: Scores 0–6

The final NPS is computed as (% Promoters - % Detractors) * 100, rounded to the nearest integer.
Sources: src/lib/pmf/metrics.ts:7-35

Subscription Funnel Calculation

The system tracks several key performance indicators (KPIs) through the PmfSummary interface:

• Trial to Paid Rate: The ratio of paid active users to total signups.
• Active Retention: The ratio of non-canceled subscriptions to the total count.
  Sources: src/lib/pmf/service.ts:81-88, src/lib/pmf/metrics.ts:38-51

This flowchart illustrates the logic contained within the computeNps function.
Sources: src/lib/pmf/metrics.ts:20-35

PMF Service & Admin Security

Administrative access to PMF metrics is strictly controlled via an environment-variable-backed allowlist (PMF_ADMIN_EMAILS).

Security Workflow

The requirePmfAdmin function performs a multi-step check before granting access to aggregate data:

1. Authentication: Verifies the caller is a signed-in user.
2. Authorization: Normalizes the user's email and checks it against the PMF_ADMIN_EMAILS list (case-insensitive, handles comma/space separation).
3. Data Retrieval: Uses a service-role client (createAdminClient) to bypass RLS and aggregate all user responses for the dashboard.
   Sources: src/lib/pmf/service.ts:70-79, src/lib/pmf/metrics.ts:80-92

API and Service Methods

Function	Input	Purpose
submitNps	score, comment, channel	Saves a user's 0-10 score; tracks nps_submitted event.
submitChurnSurvey	reason, comment, channel	Saves cancellation reason; tracks subscription_canceled event.
getPmfSummary	-	Aggregates NPS (overall and by channel), Churn, and Funnel stats.
Sources: src/lib/pmf/service.ts:25-135

Churn Management

Churn analysis is handled through predefined reasons that users select during the cancellation flow. This allowlist of reasons is enforced both at the database level (SQL check constraint) and in the application logic.

Canonical Churn Reasons

The system recognizes the following reasons for user churn:

• too_expensive
• missing_features
• not_using
• switched_tool
• one_time_need
• other
  Sources: src/lib/pmf/metrics.ts:58-65, supabase/migrations/0016_pmf_validation.sql:44-46

This diagram outlines the process of recording a cancellation survey and triggering associated analytics.
Sources: src/lib/pmf/service.ts:50-68

Summary

The PMF Metrics & Churn Management module provides a robust framework for monitoring the health of the Comply-Quick platform. By integrating raw feedback collection with secure administrative aggregation and automated analytics tracking, it allows the team to make data-driven decisions regarding product development and retention strategies. The clear separation between data storage, pure metric computation, and the presentation layer ensures that these critical KPIs remain accurate and verifiable through extensive unit testing.
Sources: src/tests/pmf-metrics.test.ts:1-60, src/app/dashboard/pmf/page.tsx:37-101