Spark 2.0 Overall Architecture

Guest identity — same shape as PWA Kit step 2 (S5): same SLAS endpoint, same grant, same token lifetimes. The Spark change: the browser makes ONE session/customer call and the server sorts out identity against Redis — instead of commerce-sdk-react checking the cookie jar client-side.

sequenceDiagram
    autonumber
    participant B as Browser - Spark app
    participant CDN as Cloudflare CDN
    participant APP as Spark app server
    participant R as Redis
    participant SLAS as SLAS
    participant SFRA as Legacy SFRA

    rect rgba(103,183,247,0.07)
    Note over B,SLAS: 🆕 FIRST VISIT — 2. The SERVER sorts out identity via session/customer
    B->>CDN: GET pandora.net/en/charms/ (first time ever)
    CDN-->>B: anonymous cached HTML — page paints, no identity needed
    Note over B: SPARK CHANGE: the browser does NOT inspect tokens itself —
it makes ONE call and trusts the answer
(PWA Kit: commerce-sdk-react checks the cookie jar,
then calls /oauth2/token through the MRT proxy)
    B->>APP: GET /api/ecom-plp/session/customer (no pnd_session yet)
    APP->>SLAS: POST /oauth2/token — grant_type=client_credentials,
channel_id=en-ZA — secret from server config,
no proxy placeholder trick needed, browser never involved
    SLAS-->>APP: access_token JWT, 30 min + refresh_token, 30 days
+ guest customer_id + usid
+ Set-Cookie dwsid and dwanonymous via Hybrid Auth
    APP->>SFRA: hybrid bridge — reconcile shopper with SFRA
dwsid captured → later injected as sfdc_dwsid on every SCAPI call
    APP->>R: SPARK CHANGE: tokens stored in Redis, not browser cookies —
tokens, usid, dwsid, customerId
    APP-->>B: CustomerState · Set-Cookie: pnd_session + relayed SLAS cookies
    Note over B: PWA Kit: SDK writes cc-at_x / cc-nx-g_x cookies —
the cookie jar IS the session.
Spark: one opaque pnd_session cookie — Redis IS the session
    end

    rect rgba(95,214,139,0.07)
    Note over B,SFRA: 🔁 SECOND VISIT — pnd_session cookie returns
    B->>CDN: GET pandora.net/en/charms/ (cookie: pnd_session)
    CDN-->>B: same anonymous cached HTML — cookie never varies the document
    B->>APP: GET session/customer (cookie: pnd_session)
    APP->>R: look up session → same shopper, same wishlist — NO SLAS call
    Note over APP,SLAS: access token expired? refreshed server-side —
guest refresh token lives 30 days (same TTLs as PWA Kit)
    APP-->>B: customer state (no re-mint, no new cookie)
    end
        

Registered — current state: Spark has no login/logout of its own — the shopper signs in (and out) on the SFRA pages, exactly as today. Spark finds out on its next session/customer call: the rotated dwsid is the tripwire, the hybrid bridge re-reconciles with SLAS, and the same pnd_session upgrades to the registered shopper — basket and wishlist merge happen on the Salesforce side. Spark-owned login arrives only in 🗺 Phase 2 when SFRA retires.

sequenceDiagram
    autonumber
    participant B as Browser - Spark app
    participant APP as Spark app server
    participant R as Redis
    participant SLAS as SLAS
    participant SFRA as Legacy SFRA

    rect rgba(238,123,171,0.07)
    Note over B,SFRA: 🔐 LOGIN — happens on SFRA ONLY (current state, same as today)
    B->>SFRA: shopper signs in on an SFRA page (email + password)
    SFRA->>SLAS: SFRA + Hybrid Auth authenticate the shopper
    Note over SLAS: guest basket + wishlist
merge into the account (Salesforce side)
    SFRA-->>B: logged in · dwsid ROTATES · registered SLAS cookies set
    Note over B: Spark knows nothing yet — it finds out on its next call
    end

    rect rgba(103,183,247,0.07)
    Note over B,SFRA: 🔄 SHOPPER NAVIGATES BACK TO A SPARK PAGE
    B->>APP: GET session/customer (cookie: pnd_session + rotated dwsid)
    APP->>R: compare dwsid — rotation detected (the tripwire)
    APP->>SLAS: hybrid bridge re-reconciles → registered tokens
    APP->>R: SAME pnd_session record upgrades to the registered shopper
    APP-->>B: logged in — bag & wishlist intact, no new cookie
    end

    Note over B,SFRA: LOGOUT works the same way: SFRA logout rotates dwsid →
next session/customer detects it → Redis record back to guest
    Note over B,SFRA: Spark-owned login/logout is 🗺 Phase 2 —
only when SFRA retires per market
        

All layers in one picture (current state): edge cache → server-side identity → hearts → add to bag → rehydration. Stored session fields shown are today's — the roadmap slims them to the lean vault.

sequenceDiagram
    autonumber
    participant B as Browser - Spark app
    participant CDN as Cloudflare CDN
    participant APP as Spark app server
    participant R as Redis
    participant SLAS as SLAS
    participant SFCC as SFCC SCAPI
    participant DOL as DOL API

    Note over B,APP: 1. Guest opens a product listing page
    B->>CDN: GET pandora.net/en/charms/ with x-spark-enable cookie
    alt edge cache HIT (TTL from Cache-Control set by the Spark render)
        CDN-->>B: cached page served from Cloudflare edge — app server never invoked
    else cache MISS or non-cacheable request
        CDN->>APP: forward to SSR
        APP-->>CDN: rendered page + Cache-Control headers
        CDN-->>B: page (now cached at edge for next shopper)
    end
    Note over B: cached HTML is anonymous and shared — hearts empty,
no personal data in it. ALL personalization is layered on
client-side in steps 2-6, which is why page caching is safe.
SAME model as PWA Kit — this part carries over 1:1

    Note over B,SLAS: 2. The SERVER sorts out identity via session/customer
    Note over B: the browser does NOT inspect tokens itself —
it makes ONE call and trusts the answer
    B->>APP: GET /api/ecom-plp/session/customer
SEND: pnd_session cookie + dwsid + cc-at/cc-nx cookies if any
    APP->>R: look up session hash by pnd_session value
    alt no session, token expired, or dwsid rotated
        APP->>SLAS: POST /oauth2/token
SEND: grant_type=client_credentials, channel_id=en-ZA,
usid if one exists — secret from server config,
no proxy placeholder trick needed, browser never involved
        SLAS-->>APP: GET BACK: access_token JWT, 30 min + refresh_token, 30 days
+ guest customer_id + usid
+ Set-Cookie dwsid and dwanonymous via Hybrid Auth
        APP->>R: store customerType, customerId,
slasAccessToken per siteId, slasExpiresAt per siteId —
token fields are SITE-SCOPED, one token per market,
so a market switch never reuses another site's token —
+ refreshToken (30-day continuity, NEVER leaves the server),
usid, dwsid
    else session fresh and dwsid matches
        R-->>APP: existing identity — NO SLAS call at all
    end
    APP-->>B: GET BACK: JSON isLoggedIn, customerId, visitorId,
basketItemCount + Set-Cookie pnd_session, cc-at_x split at 4KB,
cc-nx-g_x, usid, dwsid, dwanonymous
    Note over B: SAME SLAS endpoint, called server-side.
Token lives in Redis, not browser JS.
pnd_session cookie points at Redis — Redis IS the session.
dwsid arrives directly from SLAS — no OCAPI
session-bridge call, same as PWA Kit today
    Note over R: stored fields shown are CURRENT state.
Roadmap target (vault, not mirror) — tokens + expiries
+ dwsid only. Identity decoded from the JWT,
basket/wishlist asked fresh. See roadmap section

    Note over B,DOL: 3. Hearts light up
    Note over B: useWishlist dedupes — 25 tiles share ONE request
and a module cache keyed on customerId or visitorId.
No getTokenWhenReady queue — the server owns the token
    B->>APP: GET /api/ecom-plp/wishlist/
SEND: pnd_session cookie only — no Bearer in the browser,
no LD flags, no React Query cache key mimicry needed
    APP->>DOL: GET customers/{customer_id}/product-lists
server attaches Bearer from Redis + sfdc_dwsid — always on, no flag
    DOL-->>APP: GET BACK: product ids 791726PCZ, 798087EN
    APP-->>B: wishlist product ids
    Note over B: list creation is owned by the server route — the browser
never sees list ids, only productIds in/out.
Tiles check the list, matching hearts FILL

    Note over B,DOL: 4. Guest taps an empty heart
    B->>B: optimistic — heart FILLS immediately before the network call
    B->>APP: POST /api/ecom-plp/wishlist/ with productId 792015CZ
SEND: pnd_session cookie — no client-side mutation override,
the server route attaches the Bearer
    APP->>DOL: POST product-lists add item
    DOL-->>APP: saved
    APP-->>B: ok — module cache updates every tile
    Note over B: GAP TODAY: on a 401 the tile just un-fills the heart.
No automatic re-auth retry in the client yet — planned Fix 2.
Login-caused 401s are fixed server-side by the dwsid
rotation guard (shipped in @pandora/auth 1.9.2)

    Note over B,DOL: 5. Guest taps Add to Bag — useDolBasketMutation ported to Spark
    B->>APP: add to bag request
SEND: pnd_session cookie + productId payload
    Note over APP: NO pre-refetch via getCustomerBaskets needed —
Redis already knows basketId (current state — roadmap
target asks the basket fresh), and guest-session rotation
is handled by the session bridge, not the client
    alt no basket exists yet
        APP->>DOL: POST carts — ensureBasketId
auth + channel headers owned by the dol-api client,
sfdc_dwsid always attached — no LD flags
        DOL-->>APP: new basket id
    end
    APP->>DOL: POST carts/{basketId}/items with productId payload
    DOL-->>APP: updated cart WITH line items in the response
    APP-->>B: GET BACK: cart id + item count from the SAME response
    Note over B: no 500ms propagation wait, no background basket refetch,
no LD flags — count read straight from the addItem response
via customer.setBasket, minicart count updates,
add-to-cart confirmation sheet shows

    Note over B,DOL: 6. Any NEW page load or MFE navigation — UI rehydration sequence
    Note over B: the SERVER remembers everything — Redis replays identity

    B->>APP: a. GET /api/ecom-plp/session/customer — always ONE call.
If token fresh and dwsid matches: Redis only, NO SLAS call.
If expired: refresh with the stored refreshToken.
If dwsid rotated: full re-reconcile against SLAS
    APP->>R: read identity, token, basketId
    APP-->>B: same customer_id back — identity continuity restored
PLUS isLoggedIn and basketItemCount in the SAME response

    Note over B: identity resolved — fewer parallel hooks needed because
the one response already carries login state AND basket count

    B->>APP: b. HEARTS — useWishlist (client-side, waits for shopperKey)
GET /api/ecom-plp/wishlist/ — one deduped call,
skipped if the module cache is still warm (SPA navigation)
    APP-->>B: list items — every tile compares productId, matching hearts FILL

    Note over B: c. MINICART — NO separate call.
basketItemCount already arrived in step a from session/customer.
PWA Kit needs useCustomerBaskets + pageshow listener here

    Note over B: d. ACCOUNT LINKS — NO separate call.
isLoggedIn already arrived in step a — actions-bar renders
sign-in link (guest) OR my-account menu + logout (registered).
PWA Kit needs useCurrentCustomer here

    opt newsletter-signup block is on the page
        Note over B: e. SUBSCRIPTION — NOTHING TODAY in Spark.
No newsletter component exists in the Spark apps yet
(only locale strings in ecom-home). PWA Kit does
POST /find + PATCH opt-in here. Straightforward gap — to be ported
    end

    Note over B: all widgets converge from ONE identity answer
keyed to the same customer_id — Redis is the continuity
        

The same guest journey as S4, but in today's PWA Kit — for comparison when someone asks "how does it work now?". Identity lives in the browser's cookie jar and every widget re-authenticates itself; in Spark the same journey is one server-side session/customer answer.

sequenceDiagram
    autonumber
    participant B as Browser - PWA Kit app
    participant CDN as CloudFront CDN
    participant MRT as PWA Kit server MRT
    participant SLAS as SLAS
    participant SFCC as SFCC SCAPI
    participant DOL as DOL API

    Note over B,MRT: 1. Guest opens a product listing page
    B->>CDN: GET pandora.net/en/charms/
    alt edge cache HIT (TTL from Cache-Control set by MRT render)
        CDN-->>B: cached page served from edge — MRT never invoked
    else cache MISS or non-cacheable request
        CDN->>MRT: forward to SSR
        MRT-->>CDN: rendered page + Cache-Control headers
        CDN-->>B: page (now cached at edge for next shopper)
    end
    Note over B: cached HTML is anonymous and shared — hearts empty,
no personal data in it. ALL personalization is layered on
client-side in steps 2-6, which is why page caching is safe

    Note over B,SFCC: 2. The browser sorts out its own identity via Auth.ready
    Note over B: commerce-sdk-react checks the cookie jar itself:
valid token? refreshable? nothing at all?
    B->>MRT: POST /mobify/proxy/api/shopper/auth/v1/.../oauth2/token
SEND: grant_type=client_credentials, channel_id=en-ZA,
usid if one exists, dnt preference
    Note over MRT: proxy injects Authorization Basic clientId:secret
the browser bundle only holds a placeholder
    MRT->>SLAS: forwards to the SLAS tenant endpoint
    SLAS-->>B: GET BACK: access_token JWT, 30 min + refresh_token
+ guest customer_id + usid
+ Set-Cookie dwsid and dwanonymous via Hybrid Auth
    Note over B: SDK writes the tokens into browser cookies:
cc-at_x split at 4KB, cc-nx-g_x refresh.
No server-side session, no Redis.
The cookie jar IS the session.
dwsid arrives directly from SLAS — no OCAPI
session-bridge call is made anymore

    Note over B,DOL: 3. Hearts light up
    Note over B: API calls were queued behind getTokenWhenReady,
now the token exists so they fire
    B->>DOL: GET dol-proxy/customers/customer_id/product-lists
SEND: Authorization Bearer + optional x-environment and
DOL Q3 channel headers via LD flags.
React Query cache key deliberately mimics the SCAPI key
so add/remove mutations invalidate it
    DOL-->>B: GET BACK: product ids 791726PCZ, 798087EN
    Note over B: if no wish_list exists yet, one is auto-created via
the custom shopper-customers mutation (also DOL proxy).
Tiles check the list, matching hearts FILL

    Note over B,DOL: 4. Guest taps an empty heart
    B->>DOL: POST dol-proxy/customers/customer_id/product-lists/listId/items
with productId 792015CZ — custom useShopperCustomersMutation
override attaches the Bearer itself
    DOL-->>B: saved — shared cache key updates every tile, heart fills

    Note over B,DOL: 5. Guest taps Add to Bag — useDolBasketMutation
    B->>SFCC: refetch current basket via SCAPI getCustomerBaskets
fresh basket avoids Invalid Customer after guest-session rotation
    alt no basket exists yet
        B->>DOL: POST dol-proxy/carts
SEND: Bearer from getTokenWhenReady, x-environment,
channel headers (channelType online, or Q3 names via LD flag)
+ sfdc_dwsid from dwsid cookie if LD flag
enable-dwsid-header-for-shopper-requests is on
        DOL-->>B: new basket id
    end
    B->>DOL: POST dol-proxy/carts/basketId/items with productId payload
same Bearer + headers
    DOL-->>B: item added
    Note over B: wait ~500ms for DOL to SCAPI propagation
    B->>SFCC: refetch basket (background fire-and-forget if LD flag
enable-global-atb-background-basket-refetch is on)
    SFCC-->>B: updated basket, minicart count updates,
add-to-cart confirmation sheet shows

    Note over B,DOL: 6. Any NEW page load or MFE navigation — UI rehydration sequence
    Note over B: server remembers nothing — the cookie jar replays identity first

    B->>MRT: a. Auth.ready — if cc-at still valid, NO network call.
If expired: POST /oauth2/token grant_type=refresh_token
(cc-nx-g cookie) via MRT proxy
    MRT->>SLAS: refresh if needed
    SLAS-->>B: same customer_id back — identity continuity restored

    Note over B: identity resolved — queued React Query hooks fire in parallel,
ONE request per data domain, shared by all widgets via cache key,
skipped entirely if the query cache is still warm (SPA navigation)

    B->>DOL: b. HEARTS — useCustomerProductLists (client-side, waits for customerId)
GET dol-proxy/customers/customer_id/product-lists (Bearer)
    DOL-->>B: list items — every tile compares productId, matching hearts FILL

    B->>SFCC: c. MINICART — useCurrentBasket → useCustomerBaskets
GET customers/customer_id/baskets (Bearer)
    SFCC-->>B: basket — totalItems derived from item quantities,
BagCountBadge shows count, popup data ready.
pageshow listener refetches on back/forward cache restore

    B->>SFCC: d. ACCOUNT LINKS — useCurrentCustomer
GET customers/customer_id (Bearer)
    SFCC-->>B: customer.isRegistered — actions-bar renders
sign-in link (guest) OR my-account menu + logout (registered)

    opt newsletter-signup block is on the page
        B->>DOL: e. SUBSCRIPTION — POST proxy/find with emailAddress (Bearer)
        DOL-->>B: consents — if email consent optIn === true, status
ALREADY_SUBSCRIBED and form fields are replaced with
acknowledgement. If optIn false: PATCH /customers/id opts them in
    end

    Note over B: all widgets converge independently from fresh authenticated
fetches keyed to the same customer_id — the cookies ARE the continuity