Product-market fit indicators

// pmf-events.ts
export interface PMFEvent {
  eventId: string;
  userId: string;
  sessionId: string;
  timestamp: number;
  type: PMFEventType;
  payload: Record<string, unknown>;
}

export type PMFEventType =
  | 'feature.adoption'
  | 'session.depth'
  | 'value.achieved'
  | 'feedback.submitted'
  | 'churn.risk'
  | 'retention.checkpoint';

// telemetry-client.ts
import { PMFEvent, PMFEventType } from './pmf-events';

export class PMFTracker {
  private queue: PMFEvent[] = [];
  private batchSize = 50;
  private flushInterval = 30000;

  constructor(private endpoint: string) {
    setInterval(() => this.flush(), this.flushInterval);
  }

  track(type: PMFEventType, payload: Record<string, unknown>, userId: string, sessionId: string): void {
    const event: PMFEvent = {
      eventId: crypto.randomUUID(),
      userId,
      sessionId,
      timestamp: Date.now(),
      type,
      payload
    };

    if (!this.validate(event)) return;
    this.queue.push(event);

    if (this.queue.length >= this.batchSize) {
      this.flush();
    }
  }

  private async flush(): Promise<void> {
    if (this.queue.length === 0) return;
    const batch = this.queue.splice(0, this.batchSize);
    try {
      await fetch(this.endpoint, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(batch)
      });
    } catch (err) {
      console.error('PMF telemetry flush failed', err);
      this.queue.unshift(...batch);
    }
  }

  private validate(event: PMFEvent): boolean {
    const required = ['userId', 'sessionId', 'timestamp', 'type'];
  

return required.every(key => event[key as keyof PMFEvent] != null); } }

### Step 3: Build Cohort-Aware Aggregation

Store events in a columnar datastore (ClickHouse, BigQuery, or PostgreSQL with partitioning). Create a view that normalizes events against cohort start dates to compute retention and engagement depth.

```sql
-- cohort_pmf_metrics.sql
CREATE MATERIALIZED VIEW pmf_cohort_metrics AS
SELECT
  cohort_date,
  user_id,
  COUNT(DISTINCT session_id) AS session_count,
  MAX(CASE WHEN type = 'feature.adoption' THEN 1 ELSE 0 END) AS adopted_core_feature,
  MAX(CASE WHEN type = 'value.achieved' THEN 1 ELSE 0 END) AS reached_value_threshold,
  MAX(CASE WHEN type = 'retention.checkpoint' AND timestamp - created_at <= 7 * 86400000 THEN 1 ELSE 0 END) AS d7_retained,
  MAX(CASE WHEN type = 'retention.checkpoint' AND timestamp - created_at <= 30 * 86400000 THEN 1 ELSE 0 END) AS d30_retained
FROM pmf_events
GROUP BY cohort_date, user_id;

Step 4: Implement PMF Scoring Algorithm

Compute a composite score using weighted components. The algorithm normalizes each signal to a 0-100 scale and applies configurable weights.

// pmf-scorer.ts
export interface PMFWeights {
  d7Retention: number;
  d30Retention: number;
  engagementDepth: number;
  featureAdoption: number;
  feedbackSignal: number;
}

export class PMFScorer {
  constructor(private weights: PMFWeights) {
    const total = Object.values(weights).reduce((a, b) => a + b, 0);
    if (Math.abs(total - 1.0) > 0.01) throw new Error('Weights must sum to 1.0');
  }

  calculateScore(metrics: {
    d7RetentionRate: number;
    d30RetentionRate: number;
    avgSessionDepth: number;
    featureAdoptionRate: number;
    npsFeedbackScore: number;
  }): number {
    const normalize = (val: number, min: number, max: number) =>
      Math.min(Math.max((val - min) / (max - min), 0), 1);

    const d7 = normalize(metrics.d7RetentionRate, 0.1, 0.4);
    const d30 = normalize(metrics.d30RetentionRate, 0.05, 0.25);
    const depth = normalize(metrics.avgSessionDepth, 1, 8);
    const adoption = normalize(metrics.featureAdoptionRate, 0.1, 0.6);
    const feedback = normalize(metrics.npsFeedbackScore, -100, 100);

    return (
      d7 * this.weights.d7Retention +
      d30 * this.weights.d30Retention +
      depth * this.weights.engagementDepth +
      adoption * this.weights.featureAdoption +
      feedback * this.weights.feedbackSignal
    ) * 100;
  }
}

Architecture Decisions and Rationale

1. Client vs. Server Tracking: Client-side events capture session depth and feature interaction latency. Server-side events validate conversion checkpoints and retention markers. Splitting the source prevents spoofing and ensures data integrity for financial or compliance-bound metrics.
2. Event-Driven over Batch: PMF indicators require near-real-time scoring to trigger deployment gates or resource reallocation. A streaming pipeline (Kafka, Kinesis, or NATS) feeds the scorer while maintaining durability through dead-letter queues.
3. Composite Scoring over Single Metric: Retention alone misses engagement intensity. NPS alone misses behavioral proof. A weighted composite reduces false positives and aligns engineering output with actual market validation.
4. Schema Versioning: Events must carry a schemaVersion field. Backward-compatible additions prevent pipeline breaks during product iterations.
5. Privacy by Design: Hash userId at ingestion, strip PII from payloads, and enforce retention policies at the storage layer. PMF telemetry must comply with GDPR/CCPA without sacrificing analytical fidelity.

Pitfall Guide

1. Event Sprawl: Tracking every click or scroll dilutes signal quality and inflates storage costs. Limit events to behavioral milestones that correlate with retention or value realization. Enforce a schema registry and require product sign-off before new event types.
2. Ignoring Cohort Decay: Aggregating all users masks churn patterns. Always compute metrics per acquisition cohort. A flat 20% retention rate could mean 40% for early adopters and 5% for paid acquisition, requiring entirely different engineering responses.
3. Conflating Acquisition Velocity with Retention: High sign-up volume with low D7 retention indicates distribution success, not product-market fit. Decouple acquisition telemetry from PMF scoring. Route acquisition metrics to growth dashboards; route PMF metrics to engineering capacity planning.
4. Poor Event Schema Versioning: Adding fields without versioning breaks aggregation queries and scoring pipelines. Implement semantic versioning for event schemas, maintain migration scripts, and deprecate old versions with TTL policies.
5. Neglecting Qualitative Signal Integration: Behavioral data misses context. Integrate NPS, support ticket sentiment, and in-app feedback surveys into the PMF score. Weight qualitative signals lower than behavioral proof, but never exclude them entirely.
6. Premature Threshold Tuning: Setting PMF score thresholds before establishing baselines causes false alarms. Run a 4-6 week calibration period to collect cohort data, then set thresholds at the 75th percentile of early adopter performance.
7. Missing Baseline Normalization: Scoring against absolute values ignores product maturity. Normalize metrics against cohort start dates, feature release cycles, and market seasonality. A D30 retention of 18% may be strong for a B2B SaaS tool but weak for a consumer app.

Production Bundle

Action Checklist

• Define PMF event schema: Standardize event types, payload structure, and schema versioning before instrumentation begins.
• Instrument client and server telemetry: Deploy tracking wrappers with idempotency, batching, and privacy controls.
• Build cohort-aware aggregation pipeline: Implement materialized views or streaming jobs that normalize events against acquisition dates.
• Implement weighted PMF scoring algorithm: Deploy the composite scorer with configurable weights and normalization bounds.
• Configure alerting thresholds: Set baseline calibration period, then trigger alerts when PMF score drops below 75th percentile of early cohort performance.
• Integrate qualitative feedback loops: Route NPS, support sentiment, and in-app survey data into the scoring pipeline with lower weight.
• Enforce data retention and privacy policies: Hash identifiers, strip PII, and apply TTL rules at ingestion to maintain compliance without losing analytical fidelity.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Early-stage product (<10k MAU)	Cohort retention + lightweight event tracking	Low overhead, high signal clarity, avoids over-engineering	Low storage, minimal pipeline cost
Growth-stage SaaS (10k-100k MAU)	Composite PMF score + streaming aggregation	Balances accuracy with scalability, supports deployment gates	Medium compute, requires Kafka/Kinesis
Enterprise/B2B product	Server-validated retention + qualitative integration	B2B cycles are longer; behavioral proof must align with contract renewal signals	Higher pipeline cost, lower false positive rate
Consumer app with viral loop	Engagement depth + feature adoption weighting	Viral acquisition masks retention; depth signals indicate actual fit	Medium storage, high indexing cost
Regulated industry (healthcare/finance)	Privacy-first telemetry + delayed scoring	Compliance requires data minimization; scoring can run on anonymized cohorts	Higher engineering overhead, lower compliance risk

Configuration Template

// pmf-config.ts
export const PMF_CONFIG = {
  telemetry: {
    endpoint: process.env.PMF_TELEMETRY_ENDPOINT || 'https://api.internal/pmf/events',
    batchSize: 50,
    flushIntervalMs: 30000,
    maxRetries: 3,
    retryDelayMs: 1000
  },
  scoring: {
    weights: {
      d7Retention: 0.30,
      d30Retention: 0.25,
      engagementDepth: 0.20,
      featureAdoption: 0.15,
      feedbackSignal: 0.10
    },
    thresholds: {
      green: 75,
      yellow: 60,
      red: 45
    },
    normalization: {
      d7Retention: [0.1, 0.4],
      d30Retention: [0.05, 0.25],
      avgSessionDepth: [1, 8],
      featureAdoptionRate: [0.1, 0.6],
      npsFeedbackScore: [-100, 100]
    }
  },
  pipeline: {
    retentionDays: 90,
    schemaVersion: '1.0.0',
    enableQualitative: true,
    cohortGranularity: 'day'
  }
};

Quick Start Guide

1. Install telemetry wrapper: Add the PMFTracker class to your frontend and backend repositories. Configure the endpoint and batch parameters using the provided template.
2. Define three core events: Instrument feature.adoption, value.achieved, and retention.checkpoint. Ensure each event carries userId, sessionId, and timestamp.
3. Deploy aggregation job: Run the cohort SQL view or configure a streaming job to compute D7/D30 retention, session depth, and adoption rates per acquisition date.
4. Initialize scorer: Instantiate PMFScorer with the configuration weights. Run a 14-day calibration to collect baseline metrics before enabling alerts.
5. Connect to CI/CD: Route the PMF score into your deployment pipeline. Block production releases when the score drops below the yellow threshold until retention or engagement metrics recover.