cross-sell-config.yaml

omise<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

```yaml
# 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.