Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 28 ยท Cartridges and Architecture

SFRA Architecture and Request Flow

See how a Storefront Reference Architecture request flows through controllers, the server module, middleware and templates, and how append, prepend and replace extend routes.

Every page in an SFRA storefront starts as a URL and ends as HTML, and a fixed chain of steps connects the two. If you can follow that chain, you can find the right place to change almost anything. This lesson describes the request flow, introduces the server module that controllers are built on, and explains the three ways a cartridge can change a route that another cartridge defined: append, prepend and replace.

It continues from Cartridges and the Cartridge Path. Here you will see why that lookup order matters for behavior, not just for files. The next lesson, Controllers, Routes and Middleware, looks at writing routes in detail.

SFRA code runs only on the platform, so the real controller code below is read-only. The runnable examples are stand-ins: a tiny route chain that copies the append/prepend/replace behavior. The real server module does much more (request and response objects, events, caching, error handling).

From pipelines to controllers

The older SiteGenesis storefront used pipelines: XML flow diagrams edited in a visual tool, with nodes that called scripts and decided where to go next. They were hard to diff, test and merge. SFRA replaced them with controllers: plain JavaScript files where each route is a function. Pipelines still exist in old projects, and the URL shape (Controller-Route, as in Product-Show) is a leftover from that era.

A route is addressed by controller file name and route name. The long form of a URL is:

TEXT
/on/demandware.store/Sites-RefArch-Site/en_US/Product-Show?pid=25604455

That reads: site RefArch, locale en_US, controller Product, route Show, with a query string. On a real shop, search-friendly URLs are mapped onto these addresses.

The request flow

sequenceDiagram
    participant B as Browser
    participant C as CDN and page cache
    participant S as server module
    participant R as Route steps
    participant T as ISML template
    B->>C: GET /product/lamp-1
    C->>S: cache miss
    S->>R: run middleware, then route function
    R->>R: build viewData
    R-->>S: res.render(template, data)
    S->>T: render with pdict = viewData
    T-->>B: HTML

The route steps prepare data; rendering happens after they finish.

Step by step:

  1. The platform finds the controller on the cartridge path and loads it.
  2. The server module builds req (request) and res (response) objects and runs the route's steps in order.
  3. Each step receives req, res and next. A step does its work and calls next() to continue the chain.
  4. The last step typically calls res.render('product/detail', data) or res.json(...). That records what to render; the output is produced when the chain completes.
  5. The platform renders the ISML template with the collected data available as pdict, then returns HTML (and may cache it).

A controller in SFRA

JavaScript
// Read-only: a simplified base controller (cartridge/controllers/Product.js)
'use strict';

var server = require('server');

server.get('Show', function (req, res, next) {
    var ProductFactory = require('*/cartridge/scripts/factories/product');
    var product = ProductFactory.get({ pid: req.querystring.pid });

    res.render('product/productDetails', { product: product });
    next();
});

module.exports = server.exports();

Three things are worth noticing. The route name is the first argument of server.get. Everything after it is a step (you can pass several, which is how middleware is added). And the file ends with module.exports = server.exports(), which hands the registered routes to the platform.

viewData

res.render(template, data) is one way to pass data to a template. The other is viewData, a shared bag on the response that every step can read and write:

JavaScript
// Read-only: adding to viewData in a step
var viewData = res.getViewData();
viewData.badge = 'New';
res.setViewData(viewData);
next();

At render time, the data passed to res.render and the viewData are merged, and the template reads them as pdict.product, pdict.badge and so on. Because viewData is shared, later steps (including steps from other cartridges) can enrich a response without knowing how the earlier steps built it. That is the heart of SFRA's extensibility.

Extending a route: append, prepend, replace

Suppose plugin_wishlists wants to add a "can wishlist" flag to the product page. It must not copy the base controller. Instead it extends the base module:

JavaScript
// Read-only: plugin_wishlists/cartridge/controllers/Product.js
'use strict';

var server = require('server');
var page = module.superModule;      // the same file, further down the cartridge path
server.extend(page);                // copy the base routes into this module

server.append('Show', function (req, res, next) {
    var viewData = res.getViewData();
    viewData.canWishlist = true;
    res.setViewData(viewData);
    next();
});

module.exports = server.exports();

module.superModule resolves to the file with the same relative path in the next cartridge on the path, which for a plugin ahead of the base is app_storefront_base's Product.js. After server.extend(page), you have a copy of every base route, and you can change them:

Call Effect
server.append('Show', fn) Run fn after the existing steps
server.prepend('Show', fn) Run fn before the existing steps
server.replace('Show', fn) Throw away the existing steps and use fn

Append is the safest default, and prepend is right for guards such as redirecting a disallowed country before any work happens. Replace is the heavy hammer: it removes everything earlier cartridges added, including other plugins' appends. Use it only when you truly own the entire route.

flowchart LR
    P["prepend steps"] --> S["existing steps<br/>(base + earlier layers)"] --> A["append steps"]
    X["replace"] -.->|"discards"| S

Prepend and append wrap the existing chain; replace swaps it out.

JS A mini route chain with append and prepend (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice that the guard stops the chain simply by not calling next(), and that extending a server copies the routes: the base is untouched. In the real module, extension works through the cartridge path instead of explicit variables, but the layering is the same.

Why replace is dangerous

The same layering shows what goes wrong when a cartridge replaces a route. Layers are applied from the base outward, so the overlay (leftmost on the cartridge path) is applied last, and a replace there deletes what the plugins contributed.

JS What replace removes (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The replacing overlay silently drops both plugins. Teams usually adopt a rule: extend with append and prepend, and replace only inside project-owned controllers.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does a route step do to continue the chain?

    Each step receives next and calls it to hand control to the following step. Not calling it stops the chain, which guards use on purpose.
  2. 2. What is module.superModule inside a controller?

    It points down the cartridge path, so a plugin or overlay can extend the controller it overlays.
  3. 3. Which call is the most likely to break another plugin's behavior on the same route?

    Replace discards all earlier steps, including anything contributed by plugins, so use it only for routes you own.
  4. 4. Where does a template find the values a step put in viewData?

    The merged viewData and render data are exposed to ISML templates as pdict.
  5. 5. In the request flow, when is the ISML template rendered?

    Steps only describe what to render. The platform renders the template when the chain completes.

Summary

  • SFRA replaced XML pipelines with JavaScript controllers; routes are addressed as Controller-Route.
  • A route is a chain of steps that call next(); res.render and res.json describe the response, and viewData collects data on the way.
  • module.superModule and server.extend let a cartridge build on the same-named controller further down the path.
  • append and prepend wrap existing steps; replace discards them and should be used rarely.
  • Template data arrives as pdict, and rendering happens after the chain completes.

Next: Controllers, Routes and Middleware