retention-rules.yaml

= await this.store.getUserState(event.userId);

// Update state based on event
await this.store.updateUserState(event.userId, this.deriveStateUpdate(event));

// Evaluate rules
for (const rule of this.rules) {
  if (rule.condition(event, userState)) {
    const lastTriggered = await this.store.getLastTriggered(rule.id, event.userId);
    const now = Date.now();

    if (!lastTriggered || (now - lastTriggered > rule.cooldown)) {
      await rule.action(event.userId, userState);
      await this.store.recordTrigger(rule.id, event.userId, now);
    }
  }
}

}

private deriveStateUpdate(event: RetentionEvent): Partial<any> { // Logic to transform event into state delta if (event.type === 'session_abandoned') { return { consecutiveAbandonments: (event as any).payload.errorCount > 0 ? 1 : 0 }; } return {}; } }

#### 3. Example Rule: Onboarding Friction Detection

A concrete rule that detects users abandoning sessions due to errors and triggers a support intervention.

```typescript
// rules/onboarding-friction.ts
import { RetentionRule, SessionAbandonedEvent } from '../rule-engine';
import { RetentionEvent } from '../retention-events';

export const onboardingFrictionRule: RetentionRule = {
  id: 'rule-onboarding-friction',
  name: 'Onboarding Error Intervention',
  condition: (event: RetentionEvent, state: any) => {
    if (event.type !== 'session_abandoned') return false;
    const sessEvent = event as SessionAbandonedEvent;
    
    // Trigger if user is in onboarding, has errors, and is a new user
    return (
      state.onboardingStage === 'active' &&
      sessEvent.payload.errorCount > 2 &&
      state.accountAgeHours < 24
    );
  },
  action: async (userId: string, state: any) => {
    // Dispatch a contextual in-app message or email
    await dispatcher.send(userId, {
      type: 'in_app_message',
      template: 'onboarding_help',
      data: { stage: state.onboardingStage }
    });
  },
  cooldown: 3600000 // 1 hour cooldown to prevent spam
};

4. Action Dispatcher with Rate Limiting

Prevents notification fatigue by enforcing global and per-user limits.

// action-dispatcher.ts
import { RedisClientType } from 'redis';

export class ActionDispatcher {
  constructor(private redis: RedisClientType) {}

  async send(userId: string, action: any): Promise<boolean> {
    // Check global rate limit
    const globalKey = `rl:global:${action.type}`;
    const globalCount = await this.redis.incr(globalKey);
    if (globalCount === 1) {
      await this.redis.expire(globalKey, 60); // Reset every minute
    }
    if (globalCount > 1000) return false; // Global cap

    // Check user-specific rate limit
    const userKey = `rl:user:${userId}:${action.type}`;
    const userCount = await this.redis.incr(userKey);
    if (userCount === 1) {
      await this.redis.expire(userKey, 3600); // Reset every hour
    }
    if (userCount > 3) return false; // User cap: max 3 emails/hour

    // Execute action (e.g., push notification, email)
    await this.executeAction(userId, action);
    return true;
  }

  private async executeAction(userId: string, action: any): Promise<void> {
    // Integration with notification providers
    console.log(`Dispatching ${action.type} to ${userId}`, action);
  }
}

Architecture Rationale

• Idempotency: The recordTrigger method ensures that if an event is replayed or processed twice, the action is not duplicated.
• Decoupling: Rules are defined separately from the engine. Product teams can add new rules by updating the configuration without touching the core service code.
• Scalability: The Redis-backed rate limiter allows the dispatcher to scale horizontally while maintaining consistent throttling logic.

Pitfall Guide

Common Mistakes and Best Practices

1. High Latency Feedback Loops

   • Mistake: Processing retention events in nightly cron jobs.
   • Impact: Interventions arrive too late to influence behavior.
   • Best Practice: Implement stream processing for critical retention signals. Use WebSockets or Server-Sent Events for real-time in-app updates.

2. Notification Fatigue

   • Mistake: Triggering actions based on single events without frequency capping.
   • Impact: Users mute notifications or uninstall the app.
   • Best Practice: Implement multi-tier rate limiting (global, per-user, per-channel). Use suppression lists based on user preferences.

3. Schema Drift and Data Quality

   • Mistake: Allowing event payloads to change without versioning, breaking downstream rules.
   • Impact: Rules fail silently, or worse, trigger incorrect actions.
   • Best Practice: Enforce schema validation at ingestion. Use schema registries. Version events and handle legacy schemas gracefully.

4. Coupling Retention Logic to Business Code

   • Mistake: Hardcoding retention triggers inside API handlers.
   • Impact: Retention logic becomes untestable and requires full deployments to change.
   • Best Practice: Emit events and let the retention engine handle logic. Keep business services stateless regarding retention.

5. Ignoring the Cold Start Problem

   • Mistake: Applying churn prediction models to new users without sufficient data.
   • Impact: False positives lead to annoying interventions for engaged new users.
   • Best Practice: Implement a "warm-up" period for new users. Use heuristic-based rules for onboarding and switch to ML models only after sufficient signal accumulation.

6. Lack of Experimentation Framework

   • Mistake: Rolling out retention campaigns to 100% of users without A/B testing.
   • Impact: Inability to measure lift; risk of negative impact on retention.
   • Best Practice: Integrate retention actions with an experimentation platform. Always run holdout groups. Measure incremental lift, not just correlation.

7. Privacy Violations in Behavioral Tracking

   • Mistake: Storing PII in analytics events or tracking sensitive behaviors without consent.
   • Impact: GDPR/CCPA violations, legal risk, loss of trust.
   • Best Practice: Anonymize PII at ingestion. Implement consent management. Ensure retention rules only operate on pseudonymized IDs.

Production Bundle

Action Checklist

• Define Retention Events: Document core events (e.g., feature_adopted, session_abandoned, payment_failed) with strict schemas.
• Implement Event Ingestion: Deploy a message broker and ensure all services emit events asynchronously.
• Build State Store: Set up Redis/DynamoDB for low-latency user state and rule cooldown tracking.
• Deploy Stream Processor: Implement the rule engine using a stream processing framework or service.
• Configure Rate Limiting: Define global and per-user limits for all retention channels.
• Establish Experimentation: Integrate retention actions with A/B testing infrastructure to measure lift.
• Monitor Pipeline Health: Set up alerts for event lag, rule evaluation failures, and action dispatch errors.
• Review Privacy Compliance: Audit event payloads and retention logic for PII and consent adherence.

Decision Matrix

Configuration Template

A YAML-based configuration for defining retention rules without code changes. This can be loaded by the rule engine at runtime.

# retention-rules.yaml
rules:
  - id: rule-onboarding-error
    name: "Onboarding Error Intervention"
    trigger_event: "session_abandoned"
    condition:
      and:
        - path: "payload.errorCount"
          operator: "gt"
          value: 2
        - path: "state.onboardingStage"
          operator: "eq"
          value: "active"
        - path: "state.accountAgeHours"
          operator: "lt"
          value: 24
    action:
      type: "in_app_message"
      template: "onboarding_help"
      cooldown_ms: 3600000

  - id: rule-weekly-engagement
    name: "Weekly Re-engagement"
    trigger_event: "timer_weekly"
    condition:
      and:
        - path: "state.lastActiveDays"
          operator: "gte"
          value: 7
        - path: "state.plan"
          operator: "eq"
          value: "free"
    action:
      type: "email"
      template: "weekly_digest_promo"
      cooldown_ms: 604800000

rate_limits:
  global:
    email: 1000
    push: 5000
  user:
    email: 3
    push: 10
  window_minutes: 60

Quick Start Guide

1. Initialize Schema Registry: Define your retention events in a schema file and register them with your event broker. Ensure all services validate against this schema.

   npm install @codcompass/retention-schema
   # Configure schema registry URL in .env
   

2. Deploy Rule Engine Service: Use the provided TypeScript template to deploy the retention engine. Connect it to your message broker and Redis store.

   docker-compose up -d retention-engine redis
   

3. Load Configuration: Upload the retention-rules.yaml to your configuration store or load it via the admin API. Verify rules are loaded by checking the engine logs.

4. Simulate Events: Use a CLI tool or test script to emit sample events and verify that rules trigger actions correctly. Check Redis for cooldown entries.

   npx retention-cli simulate --event session_abandoned --user user_123
   

5. Monitor and Iterate: Set up a dashboard for rule triggers, action dispatch success rates, and retention lift. Refine conditions based on performance data.

Retention is a system, not a feature. By engineering your retention infrastructure with real-time capabilities, strict schema governance, and decoupled logic, you transform user engagement from a reactive marketing activity into a predictable, scalable engineering outcome.