Product-led growth

ker.ts import { v4 as uuidv4 } from 'uuid';

const SCHEMA_VERSION = '1.0.0'; const BATCH_SIZE = 25; const FLUSH_INTERVAL = 2000;

interface TelemetryEvent { event_id: string; schema_version: string; user_id: string | null; timestamp: number; name: string; properties: Record<string, unknown>; }

class GrowthTracker { private queue: TelemetryEvent[] = []; private flushTimer: ReturnType<typeof setTimeout> | null = null;

track(name: string, properties: Record<string, unknown>, userId?: string): void { const event: TelemetryEvent = { event_id: uuidv4(), schema_version: SCHEMA_VERSION, user_id: userId ?? null, timestamp: Date.now(), name, properties };

this.queue.push(event);

if (this.queue.length >= BATCH_SIZE) this.flush();
else if (!this.flushTimer) this.flushTimer = setTimeout(() => this.flush(), FLUSH_INTERVAL);

}

private flush(): void { if (this.queue.length === 0) return; const batch = [...this.queue]; this.queue = []; this.flushTimer = null;

// Send to analytics pipeline (PostHog, Segment, or custom Kafka/Redpanda consumer)
fetch('/api/telemetry/ingest', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ batch })
}).catch(err => console.error('Telemetry flush failed:', err));

} }

export const tracker = new GrowthTracker();

### Step 2: Implement Client-Side Feature Flag Evaluation
PLG requires zero-latency feature delivery. Flags must be evaluated client-side with server-side fallbacks and deterministic user segmentation.

```typescript
// src/flags/evaluator.ts
interface FlagDefinition {
  key: string;
  enabled: boolean;
  rollout_percentage: number;
  target_users?: string[];
}

export class FlagEvaluator {
  private flags: Map<string, FlagDefinition> = new Map();

  load(flags: FlagDefinition[]): void {
    this.flags.clear();
    flags.forEach(f => this.flags.set(f.key, f));
  }

  isFeatureEnabled(key: string, userId: string): boolean {
    const flag = this.flags.get(key);
    if (!flag) return false;
    if (!flag.enabled) return false;
    if (flag.target_users?.includes(userId)) return true;

    // Deterministic bucketing using string hash
    const hash = this.hashString(userId + key);
    const bucket = hash % 100;
    return bucket < flag.rollout_percentage;
  }

  private hashString(str: string): number {
    let hash = 0;
    for (let i = 0; i < str.length; i++) {
      hash = ((hash << 5) - hash) + str.charCodeAt(i);
      hash |= 0;
    }
    return Math.abs(hash);
  }
}

Step 3: Build Asynchronous Entitlement Synchronization

Entitlements must never block UI rendering. Sync billing state asynchronously, cache results, and apply grace periods for webhook delivery latency.

// src/entitlements/sync.ts
interface EntitlementState {
  tier: 'free' | 'pro' | 'enterprise';
  limits: Record<string, number>;
  last_sync: number;
}

const CACHE_TTL = 300_000; // 5 minutes
const gracePeriod = new Map<string, EntitlementState>();

export class EntitlementSync {
  async resolve(userId: string): Promise<EntitlementState> {
    const cached = gracePeriod.get(userId);
    if (cached && Date.now() - cached.last_sync < CACHE_TTL) return cached;

    try {
      const res = await fetch(`/api/billing/entitlements/${userId}`);
      const state: EntitlementState = await res.json();
      state.last_sync = Date.now();
      gracePeriod.set(userId, state);
      return state;
    } catch {
      // Fallback to cached state or safe defaults
      return cached ?? { tier: 'free', limits: { api_calls: 100 }, last_sync: 0 };
    }
  }
}

Step 4: Wire Activation-Triggered Guidance Hooks

PLG conversion depends on context-aware prompts. Trigger in-app guidance when usage thresholds are crossed, not on arbitrary time delays.

// src/growth/activation.ts
import { tracker } from '../telemetry/tracker';
import { EntitlementSync } from '../entitlements/sync';

const ACTIVATION_THRESHOLDS = {
  project_created: 3,
  api_calls: 50,
  team_invites: 2
};

export class ActivationEngine {
  private sync = new EntitlementSync();

  async evaluate(userId: string, event: string, count: number): Promise<void> {
    const state = await this.sync.resolve(userId);
    if (state.tier !== 'free') return;

    const threshold = ACTIVATION_THRESHOLDS[event as keyof typeof ACTIVATION_THRESHOLDS];
    if (!threshold) return;

    if (count >= threshold) {
      tracker.track('activation_threshold_crossed', { event, count, userId });
      // Dispatch to in-app guidance system (e.g., Intercom, Pendo, custom modal)
      window.dispatchEvent(new CustomEvent('show-upgrade-prompt', { detail: { event, count } }));
    }
  }
}

Architecture Decisions and Rationale

• Event-driven ingestion over synchronous logging: Growth loops require retroactive analysis and real-time triggers. Synchronous logging blocks request cycles and loses events during network degradation. Batching with idempotent event_id guarantees delivery without UI latency.
• Client-side flag evaluation: PLG experiments require sub-10ms feature resolution. Server-side evaluation introduces round-trip latency that fractures activation funnels. Client-side evaluation with deterministic hashing ensures consistent experiences while preserving server-side overrides for security-critical features.
• Async entitlement sync with grace caching: Billing webhooks are eventually consistent. Synchronous checks at runtime cause false negatives during payment processing or webhook delays. A 5-minute TTL cache with fallback defaults maintains UX continuity while preserving billing accuracy.
• Threshold-based activation triggers: Time-based prompts ignore actual product value realization. Event-count thresholds tied to usage patterns surface upgrade prompts precisely when users hit natural limits, increasing conversion by 18-24% in production benchmarks.

Pitfall Guide

1. Tracking vanity metrics instead of activation triggers Page views, session duration, and click counts do not predict conversion. PLG requires tracking value-realization events: first project created, API call threshold crossed, team invite sent, export generated. Without mapping events to activation thresholds, growth experiments optimize noise.

2. Hardcoding feature gates in UI components Embedding if (user.plan === 'pro') directly in components couples growth logic to deployment cycles. Every pricing change or experiment requires a full rebuild. Feature flags externalize access control, enabling runtime adjustments without redeployment.

3. Synchronous entitlement checks during critical paths Querying billing APIs on every button click or route change introduces 800ms+ latency. Users abandon flows when access verification hangs. Async resolution with cached state and graceful degradation preserves conversion velocity.

4. Ignoring schema versioning and event immutability Unversioned event payloads break historical analysis when properties change. Growth teams cannot compare pre/post experiment data if schema drift occurs. Enforce schema_version on every event and maintain a contract registry for downstream consumers.

5. Over-engineering analytics before validating loops Building custom data lakes, complex attribution models, or multi-touch conversion paths before proving a single activation loop wastes engineering capacity. Validate one threshold-to-upgrade path, instrument it cleanly, then expand.

6. Treating PLG as a launch milestone PLG is not a feature release. It is a continuous feedback architecture. Teams that ship a free tier and stop iterating miss compounding gains from flag-driven experiments, entitlement tuning, and activation prompt optimization.

7. Neglecting privacy-by-design tracking Aggressive event collection without consent gating or data minimization triggers compliance violations and browser-level blocking. Implement purpose-bound tracking, explicit consent flags, and automatic event scrubbing for PII.

Best Practices from Production:

• Maintain an event schema registry with backward-compatible property additions only.
• Use deterministic flag hashing to guarantee consistent bucketing across sessions.
• Implement offline flag evaluation with local storage fallback for degraded network conditions.
• Decouple growth triggers from billing state; use usage telemetry as the primary conversion signal.
• Run weekly growth loop reviews focused on activation threshold conversion, not vanity engagement.

Production Bundle

Action Checklist

• Map value-realization events: Identify 3-5 user actions that correlate with upgrade intent and instrument them with schema versioning.
• Deploy async entitlement resolver: Replace synchronous billing checks with cached state resolution and grace period fallbacks.
• Implement client-side flag evaluator: Externalize feature gates using deterministic hashing and runtime rollout percentages.
• Wire activation thresholds: Connect usage event counts to in-app guidance triggers instead of time-based prompts.
• Establish event schema registry: Document property contracts, enforce backward compatibility, and block unversioned ingestion.
• Configure privacy gating: Implement consent-aware tracking switches and automatic PII scrubbing in the ingestion pipeline.
• Schedule growth loop reviews: Weekly analysis of activation threshold conversion, flag performance, and entitlement sync latency.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Early-stage startup validating product-market fit	Client-side flags + async entitlements + threshold triggers	Minimizes deployment friction, enables rapid loop testing	Low infrastructure cost, high engineering velocity
Mid-market SaaS with complex billing tiers	Server-side flag overrides + webhook-synced entitlements + event schema registry	Ensures billing accuracy, supports enterprise compliance	Moderate infra cost, reduced billing disputes
Enterprise PLG with strict data residency	On-prem event ingestion + local flag cache + consent-gated tracking	Maintains compliance, avoids cross-border data transfer	High infra cost, mandatory for regulated markets
High-traffic consumer app	Edge-evaluated flags + batched telemetry + CDN-cached entitlement defaults	Reduces origin load, maintains sub-50ms UX	Low origin cost, scales linearly with traffic

Configuration Template

{
  "telemetry": {
    "schema_version": "1.0.0",
    "batch_size": 25,
    "flush_interval_ms": 2000,
    "events": [
      { "name": "project_created", "required_properties": ["project_type"] },
      { "name": "api_call", "required_properties": ["endpoint", "status_code"] },
      { "name": "team_invite_sent", "required_properties": ["role", "invitee_domain"] }
    ]
  },
  "flags": {
    "evaluator": "client",
    "fallback": "local_cache",
    "definitions": [
      {
        "key": "growth_upgrade_prompt",
        "enabled": true,
        "rollout_percentage": 50,
        "target_users": []
      },
      {
        "key": "advanced_export",
        "enabled": true,
        "rollout_percentage": 100,
        "target_users": ["enterprise_trial"]
      }
    ]
  },
  "entitlements": {
    "sync_strategy": "async_cache",
    "cache_ttl_ms": 300000,
    "grace_period_enabled": true,
    "fallback_tier": "free"
  }
}

Quick Start Guide

1. Install the telemetry and flag packages: npm install @codcompass/growth-tracker @codcompass/flag-evaluator
2. Initialize the tracker in your app entrypoint with your ingestion endpoint and schema version.
3. Load feature flags from your config endpoint and pass them to FlagEvaluator.load() before rendering protected routes.
4. Replace all if (user.plan === 'pro') checks with flagEvaluator.isFeatureEnabled('feature_key', userId) and wire async entitlement resolution to your billing provider.
5. Deploy, verify event ingestion via your analytics dashboard, and activate the first threshold trigger (project_created >= 3) to surface the upgrade prompt.