🔬 Order Tracker — Deep Dive (GraphQL · Salesforce Apex · ROAM)

Companion to ORDER_TRACKER_END_TO_END.md. That doc covers the whole pipeline; this one drills into the three areas you asked about:

1. The GraphQL read path — what GraphQL? serves vs. what REST? serves
2. The Salesforce Apex publisher — how/when the event is created (the producer)
3. ROAM mobile

Grounded in real code. Where a fact came from a sub-agent's file read rather than a line I personally re-opened, it's still file-cited so you can verify.

#1. 🔌 The GraphQL Read Path

#1.1 The headline (important!)

cart-service runs a GraphQL API (Netflix DGS), but the order tracker — the progress bar — does NOT use it. The tracker timestamps are served only by REST (GET cart/v1/orders). GraphQL serves the cart / commerce side of an order: the vehicle, the cost breakdown (cash/finance/lease), trade-ins, taxes, incentives? — plus a few small "hints."

Verified two ways:

• A grep across every *.graphqls schema file finds no progressState, trackerPhase, or per-milestone timestamp field.
• The web tracker (useOrderSteps.ts) reads OrderProgressState from useCartOrderQuery.ts, which is a plain REST GET cart/v1/orders — not a GraphQL query.

🔑 Rule of thumb: "Where am I in the delivery?" → REST. "What did I buy, for how much, with which trade-in/taxes/finance terms?" → GraphQL.

#1.2 The query surface (what GraphQL actually exposes)

cart-service? uses Netflix DGS (@DgsComponent / @DgsQuery / @DgsData). The schema is split across several files under cart-service/routes/src/main/resources/schema/ (queries.graphqls, mutations.graphqls, enums.graphqls, outputTypes/payloads.graphqls, outputTypes/cart/*.graphqls, outputTypes/orderDetails/*.graphqls).

There is one order-relevant root query (schema/queries.graphqls):

type Query {
    getCurrentCart: CurrentCartPayload      # the customer's current ACTIVE/SUBMITTED/CLOSED cart
    # …plus dealership/lookup queries…
}

# outputTypes/payloads.graphqls
interface CartPayload { cart: Cart!  orderDetails: OrderDetails  hints: CartHints }
type CurrentCartPayload implements CartPayload {
    cart: Cart!
    orderDetails: OrderDetails
    hints: CartHints
}

# outputTypes/orderDetails/orderDetails.graphqls  — a UNION by payment type (cost breakdown)
union OrderDetails =
    CashOrderDetails | FinanceOrderDetails | LeaseOrderDetails | InterestedInLeaseOrderDetails
# e.g. FinanceOrderDetails { billboard, vehicleCost, incentives, tradeIn,
#                            careAndProtectionPlans, shippingAndTaxes,
#                            estimatedFinancedAmountInCents, … }

# outputTypes/cart/hints.graphql
type CartHints {
    statusHint: StatusHint!
    sourceAction: SourceAction!
    orderHints: OrderHints          # ← the ONLY order-domain data in GraphQL
    paymentOptions: [PaymentOptionHint!]!
    # …tradeInOptions, incentiveOptions, financeHints, preQualificationHint, localDealerHints…
}
type OrderHints { orderNumber: String! }   # just the order number — NOT the tracker steps

Relevant enums (schema/enums.graphqls / hints.graphql):

enum StatusHint  { CART_STAGED  CART_ACTIVE  CART_UNFINANCEABLE_ERROR  CART_INTERESTED_IN_LEASE
                   CART_CUSTOMER_DECLINED_FINANCE_ERROR  CART_EXPIRED  CART_CANCELED
                   ORDER_PLACED  ORDER_CANCELED }
enum SourceAction{ CART_STARTED  SELECTED_HOME_AND_DELIVERY  SELECTED_PAYMENT_OPTIONS  SELECTED_TRADE_IN
                   SELECTED_INCENTIVES  SELECTED_CARE_AND_PROTECTION  SELECTED_FINANCE_TERMS
                   SUBMITTED_FINANCE_APPLICATION  FINANCE_USER_ACCEPTED  SUBMITTED_ORDER
                   CART_LIFETIME_TIMEOUT  CART_MANUAL_CANCEL  … }

⚠️ Note: OrderHints is just { orderNumber }. GraphQL does not expose canCancel, showTracker, estimatedDeliveryDate, or any progress timestamps — those live only in the REST /orders payload.

#1.3 Query → fetcher → service → converter (the map)

The whole thing resolves off one cart lookup, then each field has its own fetcher (graphql/query/CartQueries.kt, graphql/fetchers/*):

@DgsComponent
class CartQueries(private val authHelper, private val currentCartLookupOrchestrator) {
    @DgsQuery @Secured
    fun getCurrentCart(dfe): DataFetcherResult<CurrentCartPayload> {
        val userId = authHelper.getAndValidateUserId()                         // Auth0 JWT → userId
        val cart   = currentCartLookupOrchestrator.lookupCurrentCartForUser(userId)
        return DataFetcherResult.newResult<CurrentCartPayload>()
            .data(CurrentCartPayload())
            .localContext(CartContext(resultCart = cart))                      // passed to all fetchers
            .build()
    }
}

// OrderHintsFetcher — the only fetcher that touches the Order domain
@DgsData(parentType = "CartHints", field = "orderHints")
fun getOrderHints(dfe): OrderHints? =
    when (val r = getOrderOrchestrator.getOrderForCart(dfe.getLocalContext<CartContext>().resultCart)) {
        is Success  -> r.order.toOrderHints()      // → OrderHints(orderNumber = order.orderNumber)
        NotFound    -> null
    }

// StatusHintFetcher → cart lifecycle, NOT fulfillment stage
fun getStatusHintFromCart(cart): StatusHint = when (cart.status) {
    Staged    -> CART_STAGED
    Active    -> CART_ACTIVE
    is Submitted -> when (reason) { ORDER_PLACED -> ORDER_PLACED; UNFINANCEABLE -> CART_UNFINANCEABLE_ERROR; … }
    is Closed    -> when (reason) { EXPIRED -> CART_EXPIRED; CANCELED -> CART_CANCELED }
}

#1.4 Auth & a security note

Same Auth0? JWT? model as REST; each fetcher pulls userId/cart from CartContext. One thing worth flagging: in SecurityConfiguration.kt, the REST routes are explicitly .authenticated() (GET /orders, GET /cart-disposition) but the GraphQL POST endpoint currently falls under .anyRequest().permitAll() with a // TODO to lock it down. The @Secured annotation on getCurrentCart + authHelper.getAndValidateUserId() still require a valid token at the resolver level, but the HTTP filter chain itself isn't gating /graphql yet. Worth confirming before prod.

#1.5 Web consumers (which hook hits which API)

🔑 Takeaway: two read paths by design. The tracker needs raw timestamps (flat REST). The commerce screens need a rich selectable graph (GraphQL). The bridge is orderNumber/statusHint/sourceAction — lightweight GraphQL fields, no progress data duplicated.

#2. ☁️ The Salesforce Apex Publisher (the producer side)

In the first doc I said the Apex? publisher "isn't checked out." That was wrong — it is here. (I also previously guessed a TrackerPhaseResolver class and a …DynamicVehicle class — those don't exist; the real design uses trigger handlers with static status maps.) Here's the verified producer.

#2.1 Three publishers, one event

Every publisher ends in EventBus.publish(new Order_Tracker_Event__e(...)). They differ by what triggers them:

#2.2 Publisher A — CaseTriggerHandler (Case/Deal status → phase)

(file: Salesforce-FreewayCRM/.../classes/CaseTriggerHandler.cls, method dealStatusPlatformEventHandlerShop, invoked from CaseTrigger after-update) — fires only when newCase.Status != oldCase.Status and the Case? Type is Shop/Shop w/Trade. A static map decides the phase:

static final Map<String,String> statusToTrackerPhaseMapCases = new Map<String,String>{
    'Received by DCS'    => 'ORDER_CONFIRMED',
    'Received by DDS IV' => 'ORDER_CONFIRMED',
    'DMV Queue'          => 'E_SIGNATURE',
    'Deal Funded'        => 'CONTRACTS_COMPLETE',
    'Wet Docs Sent'      => 'TITLE_REG_SENT_WET_DOCS',
    'Paperwork Received' => 'TITLE_REG_RECEIVED_WET_DOCS',
    'DMV Review'         => 'TITLE_REG_SENT_DMV',
    'DMV Completed'      => 'TITLE_REG_PROCESSED_DMV',
    'Pickup Complete'    => 'VEHICLE_PICKED_UP'
};
// Special case (regression): Status == 'Option Selected' AND Send_Back_Date__c changed → 'RETURN_TO_MANAGER'

#2.3 Publisher B — VehicleTriggerHandler (Vehicle status → phase)

(file: .../classes/VehicleTriggerHandler.cls, method dealTrackerEventHandlerShop, from VehicleTrigger after-update) — fires when Vehicle__c.Status__c changes:

static final Map<String,String> statusToTrackerPhaseMapVehicles = new Map<String,String>{
    'At FF: Delivery Scheduled' => 'DELIVERY_SCHEDULED',
    'In Transit'                => 'VEHICLE_IN_TRANSIT',
    'Delivery Completed'        => 'VEHICLE_DELIVERED'
};

#2.4 Publisher C — DealStatusController.emitOrderCancelledEvent (cancellation)

This one I read in full (file: .../classes/DealStatusController.cls). It publishes only ORDER_CANCELLED, and is reached two ways:

• DealStatusInvocableAction_Dynamic.dealStatus() — an @InvocableMethod called from a Flow (e.g. Close_Case_Screen_Flow) with status == 'CANCELLED'.
• DealStatusController.publishCancelEvent() — @AuraEnabled, called from a Lightning/LWC "cancel" button.

public static String emitOrderCancelledEvent(String caseId) {
    Case record = [SELECT Account.User_Id__c, Type, Purchased_Vehicle__r.Inventory__r.VIN__c, … FROM Case WHERE Id = :caseId];
    if (record.Type?.equalsIgnoreCase('Sell')) return 'error';                 // SELL not handled
    if (String.isBlank(record.Account?.User_Id__c)) return 'error_no_user';
    String mappedCaseType = mapCaseType(record.Type);                          // Shop→SHOP, Shop w/Trade→SHOP_W_TRADE, Sell→SELL
    if (String.isBlank(mappedCaseType)) return 'error_no_case_type';
    VehicleData vehicle = resolveVehicle(record);                             // 3-priority: Purchased → Active Intent → Order-Submitted Intent
    if (vehicle == null) return 'error_no_vin';

    Order_Tracker_Event__e event = new Order_Tracker_Event__e(
        userId__c = record.Account.User_Id__c,  eventDateTime__c = DateTime.now(),
        objectType__c = 'CASE',  trackerPhase__c = 'ORDER_CANCELLED',
        caseType__c = mappedCaseType,  vin__c = vehicle.vin,  vehicleId__c = vehicle.vehicleId
    );
    Database.SaveResult result = EventBus.publish(event);                     // ← the publish
    return result.isSuccess() ? 'success' : 'error_publish_failed';
}

📝 Two things the cancel invocable also does (verified in DealStatusInvocableAction_Dynamic.cls): after a successful publish it stamps the Case (Driveway_Deal_Status__c='Canceled', DW_Status_Update_Conf__c='CANCELLED'), and it treats the legacy ORDER_COMPLETED / OUT_FOR_DELIVERY statuses as no-ops — the comment says "ORDER_COMPLETED and OUT_FOR_DELIVERY callouts removed." So completion/in-transit now come only from the Vehicle trigger, not this action.

#2.5 How the event fields are populated

Guards: the cancel path returns typed error codes (error_no_user / error_no_case_type / error_no_vin / error_publish_failed) and publishes nothing on failure; SELL cases short-circuit. Test coverage confirms this (e.g. DealStatusInvocableAction_DynamicTest.cancelled_noVehicleData_expectError asserts error_no_vin and that the Case is not updated).

#2.6 ⚠️ Producer ≠ full enum (real gaps worth knowing)

The cart-service TrackerPhase enum has 15 values, but the Salesforce producer in this repo only emits a subset. From the maps above, these phases have no producer mapping here:

• VEHICLE_PREPARED — not in either status map.
• DELIVERY_DATE_UPDATE — no Apex sets targetDate__c or this phase anywhere (grep for DELIVERY_DATE_UPDATE/targetDate in classes returns nothing). So even though cart-service + the consumer fully handle ETA updates, the SF side here doesn't appear to send them yet.

So cart-service is built to handle more phases than Salesforce currently produces — those paths are either future work, emitted by a different org/automation, or sent via a Flow not in this checkout. Flag for the team, not an assumption to rely on.

#2.7 Full producer → phase map (current reality)

#3. 📱 ROAM Mobile

#3.1 Not on this machine — confirmed

I searched broadly: find across /Users/cristianscript (depth 5), Spotlight (mdfind), and mobile markers (AndroidManifest.xml, *.xcodeproj, Podfile). No ROAM/mobile project exists locally. The only "Roam" hit is Products-Api/integration tests/Roam_API_Tests.postman_collection.json — a Postman collection for the Products API, unrelated to a mobile app. So ROAM is a remote repo not checked out; the following is the integration contract it must satisfy (inferred from the server side, not from ROAM's own source).

#3.2 How ROAM must enter the tracker flow

ROAM is a client of cart-service, exactly like the web app:

To show a tracker, ROAM must:

1. Auth with Auth0 and send Authorization: Bearer <JWT> (cart-service derives userId from the token; the read path has no userId in the URL).
2. Call GET cart/v1/orders (the REST read door, OrderController.getUserOrders). It returns a list; the web app picks the most-recent by orderedOn, and ROAM would do the same.
3. Render from progressState — the same flat timestamp bag the web useOrderSteps consumes: orderConfirmedAt, eSignatureAt, contractsCompleteAt, vehiclePreparedAt, deliveryScheduledAt, vehicleInTransitAt, vehicleDeliveredAt/vehiclePickedUpAt, plus estimatedDeliveryDate and fulfillmentMethod (to choose delivery vs pickup steps).

#3.3 What ROAM does not do

• It does not talk to Salesforce, the Pub/Sub? bus, or the order-tracker-consumer — all server-side.
• It does not receive push for tracker changes in this design; the model is pull (re-fetch cart/v1/orders; the web caches ~1h via React Query). Near?-real-time would need polling or a separate push channel.
• It does not need GraphQL for the bar; richer "my purchase" screens could use the same DGS? surface (getCurrentCart) as web.

🔎 To verify ROAM's real implementation, clone it under ~/programming (or point me at the repo) and I'll trace its actual network layer — Retrofit/Apollo/URLSession base URLs and exact endpoints — and replace this contract-based section with verified citations.

#4. 🔗 End-to-End Status Map (Salesforce status → UI bar step)

This is the single table that ties everything together: a Lithia employee changes a status in Salesforce → an Apex publisher emits a trackerPhase → cart-service stamps a field → the web UI lights up a step. Ordered by the customer's journey.

Two UI stages are deliberately not driven by Salesforce status changes:

• Order Placed — the UI synthesizes this first stage from the order's orderedOn timestamp (always shown complete; see useOrderSteps.ts, the "Order Placed" row), not from any event.
• The substeps Identity verified, Documents uploaded, Trade-in vehicle condition verified, Deposit paid, Down payment paid come from the other cart-service callbacks (identity-verification, document-upload, payment / finalize-down-payment) — not from Order_Tracker_Event__e. The UI shows them between the main stages, and useOrderSteps filters them out when they don't apply (no trade-in → drop tradeInVerifiedAt; non-finance deal → drop downPaymentPaidAt; pickup → drop the whole delivery/title cluster).

#5. 🔍 Trace: what populates VEHICLE_PREPARED?

Short answer: nothing in Salesforce emits it — yet the "Vehicle Prepared" stage still completes, via back-fill at delivery/pickup.

#5.1 The evidence

VEHICLE_PREPARED exists? at every layer except the producer:

So the direct path (applyVehiclePrepared → set vehiclePreparedAt) is wired end-to-end but is effectively dead code today — the router branch never fires because no event with trackerPhase=VEHICLE_PREPARED is ever produced.

#5.2 …but the stage still lights up — here's the trick

OrderProgressCalculator back-fills vehiclePreparedAt when the vehicle is delivered or picked up (verified in 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
    )
}
// calculatePickedUpAt does the identical back-fill of vehiclePreparedAt.

So in practice vehiclePreparedAt only ever gets a value at the VEHICLE_DELIVERED / VEHICLE_PICKED_UP moment, timestamped at the delivery/pickup time (not at an actual "vehicle prepared" moment).

#5.3 What this means for the customer's bar

• Before delivery: the "Vehicle Prepared" stage shows as the current/upcoming step (its timestamp is null), even though the car may genuinely be prepared.
• At delivery/pickup: "Vehicle Prepared" and "Vehicle Delivered/Picked Up" both flip to complete together, sharing the delivery timestamp.

#5.4 How to make it light up at the right time (the fix)

The pipeline is already built for it — only the producer is missing. To drive VEHICLE_PREPARED properly, Salesforce needs a status that maps to it, e.g. add to VehicleTriggerHandler.statusToTrackerPhaseMapVehicles:

'Ready for Delivery' => 'VEHICLE_PREPARED',   // or whatever the real Vehicle status name is

Once a Vehicle status change emits VEHICLE_PREPARED, the existing chain (applyVehiclePrepared → calculateVehiclePreparedAt → UI) lights the stage at the correct moment, and the back-fill? simply stops being the only source. Same applies to DELIVERY_DATE_UPDATE (needs an Apex path that sets targetDate__c).

🔑 Takeaway: "Vehicle Prepared" is a downstream-ready, producer-pending stage. It's not broken — back-fill guarantees the bar is never left with a gap — but today it can only ever complete retroactively at delivery, not in real time. That's the gap to close on the Salesforce side.

#6. ✅ Deep-dive TL;DR

GraphQL: cart-service is a Netflix-DGS server, but the tracker bar is REST-only (GET cart/v1/orders → full OrderProgressState). The one GraphQL query, getCurrentCart, returns Cart + OrderDetails (a Cash/Finance/Lease/InterestedInLease union of cost data) + CartHints. The only order-domain field GraphQL surfaces is OrderHints.orderNumber; statusHint (cart lifecycle) and sourceAction (last change) round out the hints. No progress timestamps in GraphQL. (Security note: /orders is .authenticated(), but the /graphql HTTP route is still permitAll with a TODO — resolver-level @Secured + JWT still apply.)

Salesforce producer: three publishers, all ending in EventBus.publish(Order_Tracker_Event__e) — CaseTriggerHandler (Case status → phase via statusToTrackerPhaseMapCases, incl. RETURN_TO_MANAGER), VehicleTriggerHandler (Vehicle status → DELIVERY_SCHEDULED/VEHICLE_IN_TRANSIT/VEHICLE_DELIVERED), and DealStatusController.emitOrderCancelledEvent (ORDER_CANCELLED, from a Flow invocable or an LWC button). Fields: userId from Account.User_Id__c, caseType mapped Shop→SHOP etc., fulfillmentMethod from the Case RecordType (PICK_UP → IN_STORE_PICKUP). No TrackerPhaseResolver class exists (earlier guess was wrong). The producer emits a subset of the 15 phases — VEHICLE_PREPARED and DELIVERY_DATE_UPDATE have no producer mapping in this repo, and ORDER_COMPLETED/OUT_FOR_DELIVERY are explicitly removed no-ops.

ROAM: not present locally (only an unrelated Products-API? Postman file mentions "Roam"). By contract it's a pull-based cart-service client — Auth0 JWT → GET cart/v1/orders → render the bar from progressState. Share the repo and I'll verify its real network layer.

Sources: cart-service (schema/*.graphqls, graphql/query/CartQueries.kt, graphql/fetchers/{OrderDetails,OrderHints,StatusHint,SourceAction,Cart}Fetcher.kt, graphql/conversions/*, config/SecurityConfiguration.kt), Salesforce-FreewayCRM (classes/CaseTriggerHandler.cls, VehicleTriggerHandler.cls, DealStatusController.cls, DealStatusInvocableAction_Dynamic.cls + tests), UI (apis/cartServices/graphQueries/*). ROAM described from integration contract — no local source found.