Digital product customer journey

const stateKey = journey:state:${event.userId}; const rawState = await this.stateStore.get(stateKey); let currentState: UserJourneyState = rawState ? JSON.parse(rawState) : { currentStep: 'INITIAL', history: [], metadata: {}, lastEventAt: 0, version: 0 };

// 4. Evaluate Rules
const applicableRule = this.rules.find(rule => 
  rule.fromState === currentState.currentStep && 
  rule.eventType === event.eventType &&
  (!rule.condition || rule.condition(event.payload))
);

if (!applicableRule) {
  // Update history even on no-op to maintain graph data
  currentState.history.push(event.eventType);
  currentState.lastEventAt = event.timestamp;
  await this.stateStore.set(stateKey, JSON.stringify(currentState));
  return { status: 'NO_TRANSITION', newState: currentState };
}

// 5. Execute Transition
currentState.currentStep = applicableRule.toState;
currentState.history.push(event.eventType);
currentState.lastEventAt = event.timestamp;
currentState.version += 1;

// 6. Persist State
await this.stateStore.set(stateKey, JSON.stringify(currentState));

// 7. Mark Idempotency
await this.stateStore.set(processedKey, '1', 'EX', 86400); // 24h TTL

// 8. Trigger Side Effects
if (applicableRule.action) {
  await applicableRule.action(currentState, event);
}

this.emit('stateTransition', { userId: event.userId, from: applicableRule.fromState, to: applicableRule.toState });

return { status: 'SUCCESS', newState: currentState };

} }

#### 3. Graph Topology Construction
While the state engine manages individual user progression, a graph database (e.g., Neo4j or Amazon Neptune) aggregates topology data. As states transition, emit events to a graph builder service that updates nodes and edges:
*   **Nodes:** Journey steps, user segments, outcomes.
*   **Edges:** Transitions with weights based on frequency and conversion probability.
*   **Rationale:** Graph storage enables efficient traversal for queries like "Find the most common path from step A to conversion" or "Identify bottleneck nodes with high drop-off rates."

#### 4. Real-Time Attribution Modeling
Implement multi-touch attribution using Shapley value approximation or Markov chains on the graph data. This moves beyond last-click models to assign credit to all touchpoints based on their removal impact on conversion probability.

### Architecture Decisions
*   **Redis for State:** Chosen for sub-millisecond read/write latency and atomic operations required for state transitions. Supports Lua scripting for complex conditional updates.
*   **Event-Driven Processing:** Decouples ingestion from processing, allowing independent scaling. Enables replay capabilities for backfilling and debugging.
*   **Idempotency at Ingestion:** Prevents state corruption from network retries or duplicate SDK sends. Critical for data integrity.

## Pitfall Guide

### 1. Over-Tracking Events
**Mistake:** Ingesting every micro-interaction without schema governance.
**Impact:** Storage costs explode, signal-to-noise ratio degrades, and processing latency increases.
**Best Practice:** Implement a strict event taxonomy. Define mandatory fields and validate payloads against a schema registry. Drop or sample low-value events at the SDK level.

### 2. Ignoring PII and Compliance
**Mistake:** Storing personally identifiable information in journey state or analytics pipelines.
**Impact:** GDPR/CCPA violations, legal liability, and potential fines.
**Best Practice:** Hash or tokenize PII at the edge. Implement data retention policies that automatically purge raw events after a defined period. Use differential privacy for aggregate reporting.

### 3. State Drift and Session Loss
**Mistake:** Relying solely on client-side storage or cookies for journey state.
**Impact:** State is lost on cache clear, device switch, or cookie rejection. User journey becomes fragmented.
**Best Practice:** Maintain authoritative state server-side. Use deterministic user stitching (e.g., email hashing) to merge anonymous and authenticated sessions. Implement fallback mechanisms for cross-device continuity.

### 4. Hardcoding Journey Paths
**Mistake:** Embedding journey logic directly in application code.
**Impact:** Inflexible, requires deployment for every change, prevents A/B testing of journey variations.
**Best Practice:** Externalize journey definitions into a configuration store or database. Load rules dynamically into the orchestrator. Enable product managers to modify paths without engineering intervention.

### 5. Linear Attribution Bias
**Mistake:** Using last-click attribution for complex, non-linear journeys.
**Impact:** Misallocation of marketing spend, optimization of low-value touchpoints, blindness to upper-funnel influence.
**Best Practice:** Adopt data-driven attribution models. Use graph algorithms to calculate the incremental value of each step. Validate models against holdout groups.

### 6. Latency in Activation
**Mistake:** Processing journey data in batch jobs that run hourly or daily.
**Impact:** Interventions arrive too late. User has already churned or encountered friction.
**Best Practice:** Architect for real-time activation. Use stream processing (e.g., Kafka Streams, Flink) to evaluate rules as events arrive. Expose journey state via low-latency APIs for immediate personalization.

### 7. Schema Drift
**Mistake:** Modifying event payloads without versioning or backward compatibility.
**Impact:** Downstream processors fail, data pipelines break, historical data becomes incomparable.
**Best Practice:** Enforce schema versioning. Use contract testing for event producers and consumers. Implement a schema registry that rejects non-compliant events.

## Production Bundle

### Action Checklist
- [ ] **Audit Event Taxonomy:** Review all tracked events against a defined schema. Remove redundant or low-value events.
- [ ] **Implement Idempotency:** Ensure all ingestion endpoints and processors check for duplicate event IDs using a distributed cache.
- [ ] **Define Transition Rules:** Document all valid state transitions and encode them in the journey rules engine.
- [ ] **PII Scrubbing:** Verify that no PII enters the analytics pipeline. Implement hashing for user identifiers.
- [ ] **Graph Topology Setup:** Deploy a graph database and configure the graph builder service to ingest transition events.
- [ ] **Attribution Model:** Select and implement a multi-touch attribution model based on product complexity.
- [ ] **Alerting:** Configure alerts for abnormal drop-off rates, state transition failures, and latency spikes.
- [ ] **Load Testing:** Simulate peak event throughput to validate state engine performance and idempotency under load.

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
| :--- | :--- | :--- | :--- |
| **Simple SaaS App** | Static Funnel + Rule Engine | Low complexity, sufficient for linear onboarding. | Low |
| **E-commerce Platform** | Graph-Based Orchestration | Non-linear paths, high need for attribution accuracy. | Medium |
| **Real-Time Gaming** | Stream Processing + Edge State | Sub-millisecond latency required, high event volume. | High |
| **Regulated Industry** | Privacy-First Graph Model | Compliance requirements dictate strict data handling. | Medium-High |
| **Rapid Prototyping** | Managed CDP Integration | Fast deployment, low engineering overhead. | Variable (SaaS fees) |

### Configuration Template

**Journey Rules Configuration (`journey-rules.json`)**

```json
{
  "version": "1.0.0",
  "rules": [
    {
      "id": "rule_001",
      "fromState": "LANDING",
      "eventType": "CLICK",
      "condition": "payload.buttonId == 'signup'",
      "toState": "SIGNUP_STARTED",
      "action": {
        "type": "EMIT_EVENT",
        "payload": { "eventType": "SIGNUP_INITIATED" }
      }
    },
    {
      "id": "rule_002",
      "fromState": "SIGNUP_STARTED",
      "eventType": "FORM_SUBMIT",
      "condition": "payload.formId == 'registration'",
      "toState": "ONBOARDING",
      "action": {
        "type": "UPDATE_METADATA",
        "payload": { "source": "organic" }
      }
    },
    {
      "id": "rule_003",
      "fromState": "ONBOARDING",
      "eventType": "ERROR",
      "condition": "payload.errorCode == 'VALIDATION_FAILED'",
      "toState": "ONBOARDING_RETRY",
      "action": {
        "type": "TRIGGER_ALERT",
        "payload": { "severity": "high", "message": "Onboarding validation failure" }
      }
    }
  ]
}

Quick Start Guide

1. Initialize Project:

   npm init -y
   npm install ioredis zod @types/node typescript ts-node
   npx tsc --init
   

2. Create Orchestrator: Save the JourneyOrchestrator code from the Core Solution section as journey-orchestrator.ts.

3. Configure Rules: Create rules.ts defining your transition rules array based on the JSON template.

4. Run Local Test:

   // test.ts
   import { JourneyOrchestrator } from './journey-orchestrator';
   import { rules } from './rules';
   
   const orchestrator = new JourneyOrchestrator('redis://localhost:6379', rules);
   
   const testEvent = {
     eventId: crypto.randomUUID(),
     userId: 'user_123',
     sessionId: 'sess_456',
     eventType: 'CLICK',
     payload: { buttonId: 'signup' },
     timestamp: Date.now(),
     source: 'web'
   };
   
   orchestrator.processEvent(testEvent).then(result => {
     console.log('Result:', result);
   });
   

5. Verify Output: Run ts-node test.ts. Check Redis for the updated state key journey:state:user_123 and confirm the transition to SIGNUP_STARTED.

Engineering the customer journey requires treating user progression as a first-class data domain. By implementing stateful orchestration, graph-based topology, and real-time activation, development teams can transform telemetry into actionable intelligence, driving measurable improvements in product performance and user satisfaction.