📦 Order Tracker — End-to-End Documentation (Rookie-Friendly)

What is this? A complete, beginner-friendly walkthrough of how Lithia/Driveway's Order Tracker works — from the moment Salesforce announces "the customer's car is now in transit," all the way to the progress bar the customer sees in the app.

It shows which system talks to which, in what order, how the stages are calculated, and exactly where Salesforce fits in. No prior knowledge assumed — there's a Glossary at the bottom.

Every claim below is grounded in real code. File paths are given so you can verify each one.

#⚠️ First, the real cast of characters

The order tracker? is not built from repos named webstore-order-tracker-api / driveway-orderdetails-api (those don't exist here). After scanning the whole workspace, here are the actual moving parts:

There's also a second, older path (Salesforce-Integration-API/routes) that pushes a few status changes to cart-service? synchronously. We cover both.

#1. 🎯 The 30-Second Summary

Here's who does what:

1. Salesforce is the brain. When a Lithia employee (or a Salesforce automation) marks a milestone done, Salesforce publishes a tiny announcement called a Platform Event (Order_Tracker_Event__e).
2. The order-tracker-consumer is the listener. It stays permanently subscribed to Salesforce's announcement channel and grabs each event the instant it appears.
3. It forwards the event to cart-service over a normal HTTP call.
4. cart-service is the recorder. It finds the customer's active order and stamps the time onto the matching milestone (e.g. vehicleInTransitAt = now). A few milestones also flip a status (order COMPLETED, delivery IN_TRANSIT). A helper (OrderProgressCalculator) keeps the timestamps tidy — back-filling earlier steps and clearing steps that no longer apply.
5. When the customer opens the app, the web UI asks cart-service for the order (with all its timestamps). The UI then calculates the current step (useOrderSteps) and draws the progress bar (RetailOrderTracker).

🧠 Quick check — the 3 layers
0/2 · 0/2 answered
1. Who decides which milestone an order has reached?
cart-service guesses from timestampsSalesforce explicitly announces itThe web UI calculates itThe order-tracker-consumer
2. What is cart-service's job in this pipeline?
Render the progress barSubscribe to SalesforceRecord timestamps (and tidy them)Decide delivery vs pickup

#2. 🗺️ The Big Picture (who talks to whom)

How to read it: Updates flow left → right (Salesforce → consumer → cart-service). The customer reads the order right → left (app ← cart-service) and computes the bar itself.

#3. 🎬 The Full Story, Step by Step (sequence diagram)

A vehicle just left the dealership and is now "in transit":

📖 Plain-English replay: Salesforce announces "in transit" (1–2). The consumer hears it, decodes the binary, hands it to the handler (3–5). The handler saves it once to avoid double-processing (6). If it's a buying order, it tells cart-service, which records the timestamp + status and remembers its place (7–11). Selling orders are skipped for now (12). Whenever the customer opens the app, cart-service returns the order and the UI computes & draws the bar (13–17).

#4. 🏢 The Repositories & Who Calls Who

#Repo 1 — Salesforce-Integration-API (the listener)

A collection of small "consumer" apps, each listening to a different Salesforce event. Ours is order-tracker-consumer (Kotlin? + Spring Boot?, coroutines).

It has effectively 3 classes:

OrderTrackerConsumer.kt   subscribes to the Salesforce topic, decodes each event
OrderTrackerHandler.kt    dedupes (Mongo), then SHOP→cart-service / SELL→skip
CartClient.kt             the actual HTTP POST to cart-service

OrderTrackerConsumer.kt — the always-on loop (file: order-tracker-consumer/.../consumer/OrderTrackerConsumer.kt):

object Constants { const val TOPIC = "/event/Order_Tracker_Event__e" }   // the "radio channel"

while (isActive) {
    val replayId = replayOffsetRepository.getReplayIdForTopic(TOPIC)       // resume bookmark
    val stub = salesforcePubSubClient.getAuthenticatedStub()              // log into Salesforce
    stub.subscribe(buildRequestFlow(TOPIC, replayId)).collect { response ->
        response.eventsList.forEach { event ->
            val schema = schemaRegistry.fetchSchema(stub, event.event.schemaId)
            when (val r = OrderTrackerEvent.fromPlatformEvent(event, schema)) {  // decode Avro
                is Success -> orderTrackerHandler.handle(r.event, event.replayId…)
                is Failure -> logger.error("Failed to deserialize …")
            }
        }
    }
}   // on any error: health gauge = 0, wait 3s, reconnect

OrderTrackerHandler.kt — dedupe + route (.../handler/OrderTrackerHandler.kt):

suspend fun handle(event, replayId) = when (eventRepository.insert(event.toEvent(replayId))) {
    is Success   -> if (event.caseType == SELL) handleSellEvent(event)   // skip (not built)
                    else handleShopEvent(event)                          // → cart-service
    is Duplicate -> Result.Duplicate                                     // already seen, skip
    is Failure   -> Result.Skip("Failed to insert event")
}

handleShopEvent also guards one rule: DELIVERY_DATE_UPDATE must include targetDate, else it's skipped.

CartClient.kt — the outbound call:

cartClient.postTrackerEvent(
    userId = event.userId,
    request = TrackerEventRequest(trackerPhase, objectType, fulfillmentMethod,
                                  caseType, completedOn = event.eventDateTime, vehicleId, vin, targetDate))
// → POST {cart-service.base-url}/callback/salesforce/users/{userId}

Config (order-tracker-consumer/src/main/resources/application.yml):

cart-service:        { base-url: the cart service (internal) }      # ← where events are forwarded
backpack:            { base-url: the Backpack service (internal) } # (for future SELL support)
salesforce-lead-submission.auth:                           # how it logs into Salesforce
  baseUrl: ${SALESFORCE_AUTH_CLIENT_URL:the Salesforce login endpoint}
  clientId/clientSecret/username/password: ${...}          # from env vars (secrets)
spring.data.mongodb.uri: ${SPRING_DATA_MONGODB_URI}        # event store

#Repo 2 — cart-service (the recorder + read API)

This repo owns the Order and its progress. It has two doors:

Key classes:

rest/salesforce/SalesforceCallbackController.kt   all the inbound callback endpoints
rest/order/OrderProgressOrchestratorRouter.kt     decides what each phase does
service/.../OrderProgressUpdateOrchestrator.kt    stamps the timestamps
service/.../CompleteOrderOrchestrator.kt          marks order COMPLETED / DELIVERED
service/.../UpdateDeliveryStatusOrchestrator.kt   sets IN_TRANSIT
service/.../components/OrderProgressCalculator.kt  builds the new OrderProgressState (back-fill/clear)
rest/order/OrderController.kt                      GET /orders (read door)
library/.../order/domain/Order.kt                 Order + OrderProgressState + enums

#Who-calls-who at a glance

#5. ☁️ The Salesforce Integration, Explained Slowly

#5.1 How the consumer "hears" Salesforce — the radio analogy

Salesforce's Pub/Sub API is a radio station:

• Salesforce broadcasts on a topic (the channel): /event/Order_Tracker_Event__e. The __e suffix = Platform Event (Salesforce's word for a broadcastable message).
• Our consumer is a radio permanently tuned to that channel, connected over gRPC to the Salesforce Pub/Sub API, waiting for events.

The event is defined as a HighVolume, PublishImmediately platform event? (verified in Order_Tracker_Event__e.object-meta.xml):

"Events to indicate the current status of a driveway order … to indicate to customers the status of their order."

#5.2 The event itself

Order_Tracker_Event__e has these custom fields (verified in .../Order_Tracker_Event__e/fields/):

The field description for trackerPhase__c says it all: "The tracker phase being signalled — main stage completion, sub-step completion, or regression trigger." (The consumer also reads an optional targetDate__c for ETA changes.)

💡 Salesforce conventions: __c = custom field, __e = platform event.

#5.3 Avro → object (decoding)

Salesforce sends events as Avro (compact binary, smaller/faster than JSON). The consumer decodes them field-by-field (OrderTrackerEvent.fromPlatformEvent) — e.g. record.get("trackerPhase__c") → TrackerPhase enum, eventDateTime__c (epoch millis) → Instant. If required fields are missing/garbled, the event is logged and dropped (the loop never crashes).

#5.4 Authenticating to Salesforce

OAuth2 password grant: the consumer logs in with clientId + clientSecret + username + password (all from environment variables), gets a token, and uses it to subscribe.

#5.5 Reliability — never miss, never double-process

Two safety nets live in the consumer's MongoDB?:

There's also a health gauge: if the Salesforce connection drops, it's set to 0 (→ Datadog? alert), the loop waits 3s and reconnects.

#6. 🧮 The Stage Calculation — The Heart of the System

This is what you asked about most: how are the stages calculated, and how does Salesforce factor in? There are three distinct layers — keep them separate in your head.

#6.1 Layer 1 — the 15 milestones Salesforce can send (TrackerPhase)

enum class TrackerPhase {
    ORDER_CONFIRMED, CONTRACTS_COMPLETE, VEHICLE_PREPARED, DELIVERY_SCHEDULED,
    VEHICLE_IN_TRANSIT, VEHICLE_DELIVERED, VEHICLE_PICKED_UP, E_SIGNATURE,
    TITLE_REG_SENT_WET_DOCS, TITLE_REG_RECEIVED_WET_DOCS,
    TITLE_REG_SENT_DMV, TITLE_REG_PROCESSED_DMV,
    DELIVERY_DATE_UPDATE, RETURN_TO_MANAGER, ORDER_CANCELLED
}

#6.2 Layer 2 — the router decides what each milestone does

When an update arrives, OrderProgressOrchestratorRouter does this (file: rest/order/OrderProgressOrchestratorRouter.kt):

1. Find the user's active order (else NoOrderFound).
2. Vehicle-swap check: if the event's vehicleId differs from the order's current vehicle, it applies a vehicle swap first (the order was reassigned to a different car — this wipes the progress so it can rebuild from the new car).
3. Dispatch on the phase → the right orchestrator.

#6.3 The exact phase → action table (verified line-by-line)

#6.4 Layer 2.5 — OrderProgressCalculator: the tidy-up helper ⭐

This is the class that actually builds the new OrderProgressState for each milestone. It is not a "which step am I on" projector — it's a set of calculate…() helpers that return an updated timestamp bag. It does two clever things a rookie should understand, because they're why the progress bar never looks broken:

(a) Back-fill earlier steps. If "Vehicle Delivered" arrives but earlier milestones were never recorded, it fills them in with the delivery time — so you never see "Delivered ✅ but Contracts ⬜". (file: service/.../components/OrderProgressCalculator.kt)

fun calculateDeliveredAt(orderProgress, vehicleDeliveredAt, fulfillmentMethod): OrderProgressState {
    val init = initOrderProgress(orderProgress, fulfillmentMethod)
    return init.copy(
        vehicleDeliveredAt  = vehicleDeliveredAt,
        vehiclePreparedAt   = init.vehiclePreparedAt   ?: vehicleDeliveredAt,   // back-fill
        contractsCompleteAt = init.contractsCompleteAt ?: vehicleDeliveredAt,   // back-fill
        orderConfirmedAt    = init.orderConfirmedAt    ?: vehicleDeliveredAt,   // back-fill
    )
}

(b) Clear steps that no longer apply (regression). Some milestones mean the order moved backwards, so later timestamps are wiped:

fun calculateVehicleInTransitAt(...) = init.copy(
    deliveryScheduledAt = null,            // in transit ⇒ "scheduled" no longer the active step
    vehicleInTransitAt  = vehicleInTransitAt,
)
fun calculateReturnToManager(...) = init.copy(  // a full regression
    titleAndRegistrationProcessedAt = null, titleSentForProcessingAt = null,
    contractsCompleteAt = null, titleAndRegistrationReceivedAt = null,
    titleAndRegistrationSentAt = null, eSignatureAt = null, orderConfirmedAt = null,
)
fun calculateVehicleSwapped(...) = init.copy(   // new car ⇒ wipe everything
    vehicleDeliveredAt = null, vehiclePickedUpAt = null, vehiclePreparedAt = null,
    /* …all other timestamps… */ estimatedDeliveryDate = null,
)

It also stamps the fulfillmentMethod onto the state so the UI knows whether to show the delivery or pickup step list. Every save goes through IncrementingOrderSaveOperator, which uses an optimistic snapshot id to prevent two updates clobbering each other (a CollisionError).

#6.5 Layer 3 — the UI calculates the current step and renders the bar

This is where "which step is the customer on" is actually decided. The web app (UI/UI2) reads the order, then useOrderSteps does the projection (file: UI/src/account/components/MyOrder/OrderDetailsTracker/useOrderSteps.ts):

1. It has a fixed, ordered list ORDER_STEP_UI_LABELS — a mix of big stage rows (Order Confirmed, Contracts Complete, Vehicle Prepared, Vehicle Delivered / Picked Up) and smaller substep rows (identity verified, documents uploaded, e-signature, title & registration steps, in-transit, delivery scheduled, …).
2. It filters the list by shipmentType (filterPickupSteps vs filterDeliverySteps), and removes downPaymentPaidAt for non-finance deals and tradeInVerifiedAt when there's no trade-in.
3. For each step: timestamp present → complete, else incomplete — using the exact field names from progressState.
4. Current stage = the earliest stage row with no timestamp (activeStageIndex).
5. It also derives a vehicleStatus chip:

const vehicleStatus =
    pickup && vehiclePickedUpAt   ? "vehiclePickedUp"
  : pickup && orderConfirmedAt    ? "preparingForPickup"
  : vehicleDeliveredAt            ? "vehicleDelivered"
  : vehicleInTransitAt            ? "vehicleInTransit"
  : contractsCompleteAt           ? "preparingForTransport"
  : orderConfirmedAt              ? "vehicleConfirmed"
  :                                 "confirmingVehicle";

There's also a coarser mapping in useCartOrderQuery.ts (mapToOrderStep) that turns deliveryStatus into a simple Submitted / InTransit / Delivered / Canceled for summary views.

🔑 The full answer to "how stages are calculated with Salesforce": Salesforce decides the milestone → cart-service records a timestamp (and OrderProgressCalculator tidies the timestamps by back-filling/clearing) → the UI projects the timestamps into a current step and renders the bar (delivery vs pickup).

#6.6 The status enums and their lifecycle

enum class OrderStatus    { ACTIVE, COMPLETED, CANCELLED }
enum class DeliveryStatus { AWAITING_SHIPMENT, IN_TRANSIT, DELIVERED }
enum class FulfillmentMethod { DELIVERY, IN_STORE_PICKUP }

#7. 🔁 The Second (Legacy) Path — PATCH /callback/salesforce/{cartId}/status

Besides the event-driven path, Salesforce-Integration-API/routes (a normal REST? service) can push a few status changes synchronously to the same cart-service controller (SalesforceCallbackController.salesforceCallback). The orchestrator methods it calls are now marked @Deprecated ("the SF callback endpoint which calls this shouldn't be used anymore") — the event path is the future:

The same controller also exposes task callbacks (/tasks/{task}/status for identity verification & document upload), Amazon third-party order callbacks, and finalize-down-payment. These feed the same Order (writing identityVerifiedAt, documentsUploadedAt, downPaymentPaidAt, …) but are outside the main tracker-phase flow.

#8. 🧱 The Data Model (cart-service Order.kt)

OrderProgressState is a flat bag of nullable UTC timestamps — null = "not reached yet."

The extra timestamps (downPaymentPaidAt, tradeInVerifiedAt, identityVerifiedAt, …) are written by the other callbacks (payment, identity, doc-upload), not the tracker-phase path. The UI shows them as substeps within the main stages.

isShadowOrder is a flag that hides certain orders from the UI; note that several orchestrators set isShadowOrder = false once Salesforce reports real progress, so the order becomes visible to the customer.

#9. 🔐 Security (Authentication) Summary

#10. 📨 Message Payloads (cheat sheet)

Salesforce → consumer (Avro?, decoded): userId__c, eventDateTime__c, trackerPhase__c, objectType__c, caseType__c, fulfillmentMethod__c, vehicleId__c, vin__c (+ optional targetDate__c).

consumer → cart-service POST /callback/salesforce/users/{userId} (OrderProgressUpdateRequest):

{
  "trackerPhase": "VEHICLE_IN_TRANSIT",
  "objectType": "VEHICLE",
  "caseType": "SHOP",
  "fulfillmentMethod": "DELIVERY",
  "completedOn": "2026-05-29T15:04:00Z",
  "vehicleId": "abc-123",
  "vin": "1HGCM82633A004352",
  "targetDate": null
}

cart-service → app GET cart/v1/orders → list of orders, each with orderStatus, deliveryStatus, fulfillmentMethod, estimatedDeliveryDate, and the full progressState of timestamps the UI reads to draw the bar.

#11. 📁 Key File Index

Salesforce-Integration-API/order-tracker-consumer/src/main/kotlin/com/lithia/salesforceintegration/

• consumer/OrderTrackerConsumer.kt — subscribes to /event/Order_Tracker_Event__e
• handler/OrderTrackerHandler.kt — dedupe; SHOP→forward, SELL→skip
• model/OrderTrackerEvent.kt — event model + Avro decode (fromPlatformEvent) + the 15 TrackerPhase values
• pubsub/client/CartClient.kt — POST to cart-service
• src/main/resources/application.yml — topic?, Salesforce auth, cart-service.base-url

cart-service/

• routes/.../rest/salesforce/SalesforceCallbackController.kt — POST /callback/salesforce/users/{userId} + legacy PATCH .../{cartId}/status + task/amazon/payment callbacks
• routes/.../rest/order/OrderProgressOrchestratorRouter.kt — phase → orchestrator (incl. vehicle-swap)
• service/.../components/OrderProgressCalculator.kt — ⭐ builds OrderProgressState (back-fill? / clear)
• service/.../orchestrators/OrderProgressUpdateOrchestrator.kt — stamps timestamps / applyReturnToManager
• service/.../orchestrators/CompleteOrderOrchestrator.kt — completeDelivery/PickupOrder (COMPLETED + DELIVERED)
• service/.../orchestrators/UpdateDeliveryStatusOrchestrator.kt — applyVehicleInTransit (IN_TRANSIT)
• routes/.../rest/order/OrderController.kt — GET /orders (read door)
• library/.../order/domain/Order.kt — Order, OrderProgressState, OrderStatus, DeliveryStatus, FulfillmentMethod

Salesforce-FreewayCRM/force-app/main/default/objects/Order_Tracker_Event__e/ — the Platform Event + 8 field definitions (trackerPhase__c is a required Text(40) field).

UI/src/account/components/MyOrder/ — OrderDetailsTracker/useOrderSteps.ts (timestamps → current step + chip), OrderDetailsTracker.tsx & RetailOrderTracker/ (the visual bar). UI/src/apis/cartServices/graphQueries/useCartOrderQuery.ts (the GET cart/v1/orders fetch + types).

#12. 📖 Glossary (plain English)

#13. ✅ TL;DR for standup

Salesforce is the source of truth for order milestones. It publishes an Order_Tracker_Event__e Platform Event whenever a milestone changes. The order-tracker-consumer (in Salesforce-Integration-API) stays subscribed via the Pub/Sub gRPC API, decodes the Avro payload, dedupes it in MongoDB (with a replay bookmark), and — for SHOP / SHOP_W_TRADE cases — forwards it to cart-service at POST /callback/salesforce/users/{userId}. cart-service's router maps the TrackerPhase to an orchestrator: most phases stamp a timestamp; VEHICLE_DELIVERED/VEHICLE_PICKED_UP set COMPLETED + DELIVERED; VEHICLE_IN_TRANSIT sets IN_TRANSIT; DELIVERY_DATE_UPDATE updates the ETA; RETURN_TO_MANAGER regresses; ORDER_CANCELLED cancels. OrderProgressCalculator keeps the timestamp bag tidy (back-fills earlier steps, clears steps that no longer apply). The Driveway web UI (useOrderSteps + RetailOrderTracker) then reads GET cart/v1/orders and computes the current step from which timestamps are filled, rendering a delivery-vs-pickup progress bar. A second legacy path (Salesforce-Integration-API/routes → PATCH /callback/salesforce/{cartId}/status, now deprecated) pushes a few statuses synchronously. SELL orders aren't handled yet (Backpack? integration pending).

Generated by scanning Salesforce-Integration-API, cart-service, UI, and Salesforce-FreewayCRM. ROAM mobile and the Salesforce Apex publisher are described from their integration contracts since their source isn't in this workspace.