Skip to main content

Architecture: Cart

This section describes the headless architecture, event-driven data flow, and the mapping process for the Cart module.

High-Level Architecture​

The Cart module is designed to be headless and event-driven, using a transformation layer to ensure the frontend works with a clean cart state regardless of the backend complexities.

Key Components​

1. The Cart Client (Headless)​

The @archibald/cart package contains the logic but no UI. The CartClient maintains the active cartId (cookie or local storage) and handles the synchronization between different components.

2. The Cart Mapper​

SAP Commerce (OCC) returns extremely verbose JSON for carts, including deep entries, multiple promotion levels, and complex delivery address objects. The CartMapper:

  • Extracts only the essential fields needed for the UI.
  • Normalizes the currency and price formatting.
  • Standardizes entry identifiers for easier mutation.

3. Event-Driven Reactivity​

Unlike standard data fetching, the cart is reactive. When addToCart is called:

  1. The mutation is sent to the BFF.
  2. The BFF returns the new, mapped cart state.
  3. The CartClient publishes a 'cart' event.
  4. All hooks (like useCart) detect the event and trigger a re-render automatically.

Connection with Other Areas​

  • Authentication: The Cart module relies on the @archibald/auth package to provide the correct security context (Anonymous JWT vs. User JWT) when talking to the SAP Commerce OCC API.
  • Merge Logic: When a user logs in, the module facilitates the "Anonymous to Registered" merge flow, ensuring that items added to a guest cart are preserved in the user's account.