ScrollWise MVP: Architecting an Onboarding & Tracking System

How I built a resilient state machine and third-party webhook architecture under strict production deadlines.

// Executive Summary

Faced with evolving client requirements and a tight timeline, the application needed a scalable onboarding workflow and absolute precision when managing third-party shipping tracking configurations.

// The Architectural Bottleneck

The primary challenge was managing asynchronous, unpredictable payload states from third-party APIs. When a user went through onboarding, multiple verification steps had to execute sequentially. If a tracking webhook dropped or fired out of order (e.g., receiving a delivery status before a pre-transit state), the local state would corrupt, stalling the client onboarding workflow.

// Engineering The Solution

I designed an event-driven status manager inside an Express backend to gracefully process incoming webhook events regardless of order. To solve tracking synchronization, I isolated data parsing layers using the Shippo SDK, ensuring payload structures were thoroughly validated via custom middleware before mutating database records. The frontend was built using a strict state machine pattern in React, completely cutting out illegal state transitions during client onboarding.

webhookHandler.jsJavaScript

// Custom tracking webhook handler with validation middleware
app.post('/api/v1/webhooks/tracking', validateShippoPayload, async (req, res) => {
  const { status, trackingNumber, metadata } = req.body;
  
  try {
    const updatedOrder = await OrderService.updateTrackingState({
      trackingNumber,
      currentStatus: status,
      updatedAt: new Date()
    });
    
    // Broadcast status change to clients securely
    NotificationEngine.emitToUser(metadata.userId, 'TRACKING_UPDATED', updatedOrder);
    return res.status(200).json({ success: true });
  } catch (error) {
    Logger.error('Tracking sync execution failure:', error);
    return res.status(500).json({ error: 'Internal State Sync Failure' });
  }
});

// Engineering Takeaways

Defensive architecture is mandatory when dealing with third-party logistics endpoints.
Keeping database schemas highly flexible early in an MVP lifecycle reduces friction when client scopes shift unexpectedly.
Isolating external SDK tracking states into unique data layers keeps long-term maintenance manageable.