/growth-engineering

name: growth-engineering
description: "Growth engineering - PLG, referral, viral loops, onboarding optimization."

Growth Engineering

PLG (Product-Led Growth) Implementation

PLG Flywheel

User Signs Up (Free)
    |
    v
Experiences Value (Aha Moment)
    |
    v
Invites Team/Colleagues
    |
    v
Team Adopts Product
    |
    v
Usage Grows -> Hits Limits
    |
    v
Converts to Paid
    |
    v
Expands (More Seats/Features)
    |
    +---> Refers New Users (loop back)

PLG Architecture

interface PLGConfig {
  freeTier: {
    features: string[];
    limits: Record<string, number>;        // { projects: 3, members: 5, storage_gb: 1 }
    duration: "unlimited" | number;         // gun cinsinden veya sinirsiz
  };
  trialTier: {
    features: string[];
    duration_days: number;
    requires_cc: boolean;
  };
  paidTiers: Array<{
    name: string;
    price_monthly: number;
    price_annual: number;
    features: string[];
    limits: Record<string, number>;
  }>;
  gates: FeatureGate[];
}

interface FeatureGate {
  feature: string;
  gate_type: "hard" | "soft" | "usage";
  free_limit?: number;
  upgrade_prompt: string;
  cta: string;
}

// Feature gate middleware
function checkFeatureGate(feature: string) {
  return async (req: Request, res: Response, next: NextFunction) => {
    const user = req.user;
    const gate = gates.find(g => g.feature === feature);

    if (!gate) return next();

    const plan = await getUserPlan(user.id);
    const usage = await getFeatureUsage(user.id, feature);

    if (gate.gate_type === "hard" && plan.tier === "free") {
      return res.status(403).json({
        error: "UPGRADE_REQUIRED",
        message: gate.upgrade_prompt,
        cta: gate.cta,
        upgrade_url: `/billing/upgrade?feature=${feature}`,
      });
    }

    if (gate.gate_type === "usage" && gate.free_limit && usage >= gate.free_limit) {
      // Soft limit: izin ver ama uyar
      res.setHeader("X-Usage-Warning", gate.upgrade_prompt);
      await trackEvent(user.id, "feature_gate_hit", { feature, usage, limit: gate.free_limit });
    }

    next();
  };
}

Aha Moment Definition

| Urun Tipi | Aha Moment Ornegi | Metrik | |-----------|-------------------|--------| | Project Management | Ilk task'i tamamlama | task_completed (first) | | Analytics | Ilk dashboard olusturma | dashboard_created (first) | | Communication | Ilk mesaj gonderme | message_sent (first) | | Development Tool | Ilk basarili build | build_succeeded (first) | | Design Tool | Ilk export/share | design_exported (first) |

interface AhaMoment {
  event: string;
  conditions: Record<string, unknown>;
  time_window_hours: number;             // Bu sure icinde olursa "activated"
  activation_rate_target: number;        // %40-60 hedef
}

const ahaMoment: AhaMoment = {
  event: "project_created_with_members",
  conditions: { member_count: { gte: 2 }, tasks_added: { gte: 3 } },
  time_window_hours: 72,                 // Kayittan sonra 72 saat icinde
  activation_rate_target: 0.50,
};

Referral System Design

Referral Architecture

interface ReferralProgram {
  id: string;
  name: string;
  reward_type: "two_sided" | "referrer_only" | "referee_only";
  referrer_reward: Reward;
  referee_reward: Reward;
  rules: ReferralRules;
}

interface Reward {
  type: "credit" | "discount" | "free_months" | "feature_unlock" | "cash";
  amount: number;
  currency?: string;
  description: string;
}

interface ReferralRules {
  max_referrals_per_user: number;        // spam onleme
  qualification_event: string;            // ne zaman odul verilir
  qualification_window_days: number;      // sure siniri
  anti_fraud: AntiFraudRules;
}

interface AntiFraudRules {
  same_ip_block: boolean;
  email_domain_block: string[];           // disposable email engelle
  min_activity_threshold: number;         // minimum kullanim
  cooldown_hours: number;                 // ayni kisi icin bekleme
}

Referral Flow

Referrer                          Referee
   |                                |
   |-- Shares unique link --------> |
   |                                |-- Signs up
   |                                |-- Completes qualification
   |                                |     (first purchase / activation)
   |<-- Notification: Reward! ------|
   |-- Reward credited              |-- Reward credited
   |                                |
   v                                v
Track: referral_completed       Track: referred_user_activated

Referral Schema

CREATE TABLE referrals (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  referrer_id UUID NOT NULL REFERENCES users(id),
  referee_id UUID REFERENCES users(id),
  referral_code VARCHAR(20) UNIQUE NOT NULL,
  referral_link TEXT NOT NULL,
  status VARCHAR(20) DEFAULT 'pending',  -- pending, signed_up, qualified, rewarded, expired
  channel VARCHAR(50),                    -- email, social, direct_link
  created_at TIMESTAMPTZ DEFAULT NOW(),
  signed_up_at TIMESTAMPTZ,
  qualified_at TIMESTAMPTZ,
  rewarded_at TIMESTAMPTZ,
  referrer_reward_amount DECIMAL,
  referee_reward_amount DECIMAL,
  metadata JSONB DEFAULT '{}'
);

CREATE INDEX idx_referrals_referrer ON referrals(referrer_id);
CREATE INDEX idx_referrals_code ON referrals(referral_code);
CREATE INDEX idx_referrals_status ON referrals(status);

-- Referral metrikleri
SELECT
  referrer_id,
  COUNT(*) AS total_referrals,
  COUNT(CASE WHEN status = 'signed_up' THEN 1 END) AS signups,
  COUNT(CASE WHEN status = 'qualified' THEN 1 END) AS qualified,
  COUNT(CASE WHEN status = 'rewarded' THEN 1 END) AS rewarded,
  ROUND(100.0 * COUNT(CASE WHEN status = 'qualified' THEN 1 END) /
    NULLIF(COUNT(CASE WHEN status = 'signed_up' THEN 1