cross-sell-config.yaml

ring; timestamp: number; metadata?: Record<string, unknown>; }

export class EventIngestor { constructor(private producer: Producer) {}

async publish(event: CrossSellEvent): Promise<void> { await this.producer.send({ topic: 'user-behavior-events', messages: [{ key: event.userId, value: JSON.stringify(event) }], }); } }

### Step 2: Real-Time Feature Store
Maintain user and item features in a low-latency store. Redis handles session context and short-term behavior; a vector database stores embeddings for collaborative filtering; Postgres holds metadata and business constraints.

```typescript
// features/feature-store.ts
import { Redis } from 'ioredis';

export class FeatureStore {
  constructor(private redis: Redis) {}

  async getUserSessionFeatures(userId: string, sessionId: string): Promise<Record<string, number>> {
    const key = `session:${sessionId}:features`;
    const raw = await this.redis.hgetall(key);
    return Object.fromEntries(Object.entries(raw).map(([k, v]) => [k, parseFloat(v)]));
  }

  async updateUserSessionFeatures(
    sessionId: string,
    updates: Record<string, number>,
    ttlSeconds: number = 1800
  ): Promise<void> {
    await this.redis.hset(`session:${sessionId}:features`, updates);
    await this.redis.expire(`session:${sessionId}:features`, ttlSeconds);
  }
}

Step 3: Hybrid Scoring Service

The scoring service combines ML-derived affinity scores with deterministic business rules. It runs asynchronously relative to the main request path, caching results and applying fallbacks when latency thresholds are breached.

// scoring/cross-sell-engine.ts
import { Redis } from 'ioredis';
import { FeatureStore } from './feature-store';
import { InventoryClient } from './inventory-client';

export interface ScoredItem {
  itemId: string;
  score: number;
  reason: string;
  margin: number;
  inStock: boolean;
}

export class CrossSellEngine {
  private readonly CACHE_TTL = 300;
  private readonly LATENCY_THRESHOLD_MS = 80;

  constructor(
    private redis: Redis,
    private featureStore: FeatureStore,
    private inventoryClient: InventoryClient
  ) {}

  async getRecommendations(
    userId: string,
    sessionId: string,
    currentItemId: string,
    limit: number = 4
  ): Promise<ScoredItem[]> {
    const cacheKey = `xsell:${userId}:${sessionId}:${currentItemId}`;
    const cached = await this.redis.get(cacheKey);
    if (cached) return JSON.parse(cached);

    const start = Date.now();
    const features = await this.featureStore.getUserSessionFeatures(userId, sessionId);
    const mlScore = this.computeAffinityScore(features, currentItemId);
    
    const businessScore = this.applyBusinessRules(currentItemId, mlScore);
    const inventoryMap = await this.inventoryClient.checkBatchAvailability(
      businessScore.map(i => i.itemId)
    );

    const scored = businessScore
      .map(item => ({
        ...item,
        inStock: inventoryMap[item.itemId] ?? false,
        finalScore: item.score * (inventoryMap[item.itemId] ? 1.0 : 0.1),
      }))
      .filter(i => i.inStock)
      .sort((a, b) => b.finalScore - a.finalScore)
      .slice(0, limit);

    const elapsed = Date.now() - start;
    if (elapsed < this.LATENCY_THRESHOLD_MS) {
      await this.redis.setex(cacheKey, this.CACHE_TTL, JSON.stringify(scored));
    }

    return scored;
  }

  private computeAffinityScore(features: Record<string, number>, currentItemId: string): number {
    const categoryAffinity = features[`cat:${this.extractCategory(currentItemId)}`] ?? 0.5;
    const recencyDecay = features['session_age_minutes'] 
      ? Math.max(0.2, 1 - (features['session_age_minutes'] / 60)) 
      : 0.5;
    return (categoryAffinity * 0.7) + (recencyDecay * 0.3);
  }

  private applyBusinessRules(currentItemId: string, mlScore: number): ScoredItem[] {
    // In production, this queries a rule engine or config service
    const candidates = this.getCandidatePool(currentItemId);
    return candidates.map(id => ({
      itemId: id,
      score: mlScore * (0.8 + Math.random() * 0.4),
      reason: 'affinity_boost',
      margin: 0.25 + Math.random() * 0.15,
      inStock: true,
    }));
  }

  private getCandidatePool(currentItemId: string): string[] {
    // Placeholder: would query vector DB or graph store
    return ['item_4421', 'item_8890', 'item_1123', 'item_5577', 'item_9002'];
  }

  private extractCategory(itemId: string): string {
    return 'electronics'; // Simplified for example
  }
}

Step 4: Architecture Decisions & Rationale

• Event-Driven Ingestion: Decouples user action tracking from scoring. Enables replay, debugging, and real-time feature updates without blocking primary flows.
• TypeScript Orchestration: Node.js/TypeScript handles high-concurrency I/O efficiently. The scoring service remains lightweight; heavy ML inference runs in separate Python services, exposed via gRPC or HTTP.
• Hybrid Scoring: Pure ML lacks margin awareness, compliance filtering, and inventory validation. Deterministic rules act as a guardrail, ensuring recommendations align with business constraints.
• Cache-First with TTL: Redis caches scored results per session/item pair. Cache invalidation triggers on cart mutations or session expiration, preventing stale recommendations.
• Fallback Circuit Breaker: If scoring latency exceeds threshold or inventory service degrades, the system returns category-popular items or static pairings, preserving UX stability.

Pitfall Guide

1. Cold-Start Paralysis New users or items lack behavioral signals. Relying solely on collaborative filtering returns empty or low-confidence results. Implement popularity-based fallbacks, category priors, and onboarding questionnaires to bootstrap features.

2. Ignoring Real-Time Inventory Recommending out-of-stock items destroys trust and increases bounce rates. Always validate availability synchronously or via a pre-warmed inventory cache before scoring. Never serve recommendations without stock validation.

3. Synchronous Scoring Blocking Checkout Tying cross-selling directly to product detail or checkout requests introduces latency spikes. Decouple scoring into background workers or async API endpoints. Use caching and fallbacks to guarantee response time SLAs.

4. Feature Store Drift Session features decay if not refreshed. Implement TTL-based expiration and event-driven updates. Without automatic decay, stale affinity scores persist, degrading recommendation relevance over time.

5. Missing Business Rule Layer ML models optimize for click probability, not profitability or compliance. Add margin thresholds, regulatory exclusions, and seasonal promotions as deterministic filters. Hybrid scoring ensures recommendations align with financial targets.

6. Measuring Correlation Instead of Incremental Lift Tracking click-through rate on recommendations doesn't prove causal impact. Use holdout groups, randomized exposure, and incremental revenue attribution to measure true lift. Optimize for margin-adjusted conversion, not raw CTR.

7. Monolithic Recommendation Services Bundling scoring, inventory checks, and rule evaluation into a single service creates bottlenecks and deployment friction. Decompose into independent workers: event processors, feature updaters, scoring engines, and rule evaluators. Communicate via message queues.

Best Practices from Production:

• Implement circuit breakers on all external dependencies (inventory, ML inference, vector search).
• Version feature pipelines and scoring configurations. Rollback capability prevents cascading failures.
• Log impressions, clicks, and cart additions for offline model retraining. Maintain a clean feedback loop.
• Use progressive enhancement: serve lightweight rules first, enrich with ML scores when latency budget allows.
• Monitor p95 latency, cache hit ratio, and fallback frequency as primary SLOs.

Production Bundle

Action Checklist

• Deploy event ingestion pipeline with schema validation and dead-letter queue handling
• Provision Redis cluster for session features and scoring cache with TTL policies
• Implement hybrid scoring service with deterministic rule overrides and inventory validation
• Configure fallback routing for latency breaches and service degradation
• Instrument telemetry: p95 latency, cache hit ratio, fallback frequency, incremental lift
• Establish A/B testing framework with holdout groups for causal measurement
• Schedule feature pipeline retraining with versioned model artifacts and rollback procedures

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
High-volume retail (>100k daily sessions)	Real-time event-driven + Redis cache + async ML scoring	Handles concurrency, maintains sub-80ms latency, scales horizontally	High infra cost, offset by 12-18% AOV lift
SaaS add-on marketplace	Rule-based scoring + feature flags + batch ML refresh	Lower session complexity, compliance-heavy, predictable catalog	Low infra cost, moderate lift (6-9%)
Low-traffic niche platform	Static pairings + category popularity + Redis caching	Minimal engineering overhead, sufficient for limited behavioral data	Near-zero infra cost, baseline lift (2-4%)
Compliance-restricted vertical (finance, healthcare)	Deterministic rules + inventory guardrails + auditable scoring	Ensures regulatory alignment, prevents prohibited pairings	Moderate cost for audit logging and rule engine

Configuration Template

# cross-sell-config.yaml
engine:
  latency_threshold_ms: 80
  cache_ttl_seconds: 300
  fallback_strategy: category_popular
  max_recommendations: 4

scoring:
  ml_weight: 0.6
  rule_weight: 0.4
  margin_floor: 0.15
  excluded_categories: ["restricted", "clearance"]

features:
  session_ttl_minutes: 30
  decay_rate: 0.05
  cold_start_default: 0.5

inventory:
  check_mode: sync_pre_score
  cache_ttl_seconds: 60
  fallback_on_timeout: true

telemetry:
  enabled: true
  metrics: ["p95_latency", "cache_hit_ratio", "fallback_rate", "incremental_lift"]
  sampling_rate: 0.1

Quick Start Guide

1. Initialize Infrastructure: Run docker compose up with Redis, Redpanda, and a mock inventory service. Verify event topic creation and schema registry connectivity.
2. Deploy Scoring Service: Build the TypeScript engine, inject configuration via environment variables, and start the HTTP/gRPC endpoint. Confirm health checks pass.
3. Seed Test Data: Publish sample view and add_to_cart events to the behavior topic. Trigger scoring API with a test session ID and verify cache population.
4. Validate Fallbacks: Simulate inventory timeout by killing the mock service. Confirm the engine returns fallback recommendations within latency threshold and logs degradation metrics.
5. Enable Telemetry: Attach Prometheus/Grafana dashboards to track p95 latency, cache hit ratio, and fallback frequency. Adjust latency_threshold_ms and cache_ttl_seconds based on observed traffic patterns.

Cross-selling is no longer a marketing afterthought. It is a distributed scoring problem requiring event-driven data pipelines, real-time feature management, and hybrid rule-ML orchestration. Implement the architecture first, refine the strategy second, and measure incremental lift continuously.