docs

Layers and Data Flow

What is each layer responsible for? A request for product data passes through four of them. A service fetches it from the SCAYLE Storefront API, a mapper turns the response into a shared type, a controller hands that type to the page as props, and a Vue page renders it. An oRPC procedure uses the same services and mappers and returns the type to the composable that called it. Each layer has one job, and knowing which job is yours is what tells you where a change belongs.

The controller asks the service for data. The service fetches from the Storefront API with caching, hands the raw response to the mapper and gets a shared type. The service returns it to the controller, which sends props to the Vue page.

Services and mappers ship as base classes in @scayle/storefront and you subclass the ones you want to change. Controllers and pages are yours from the start, though the page controllers extend an SDK base class too.

Server code lives in src/server/, client code in src/client/, and the types both sides share in src/shared/types/. Project Structure covers where a given file goes and which imports ESLint allows across those directories.

Services fetch and cache

A service calls the Storefront API, applies a cache lifetime, and hands the response to a mapper. It owns the fetching. No controller and no mapper calls the Storefront API directly, so a change to how a domain is fetched lands in one class.

Caching happens through this.context.cache.getOrSet(key, factory, ttlSeconds). What the entry holds depends on the service. Most of them map inside the callback, so the cache holds the finished shared type and a request that hits the cache skips the mapper entirely. ProductDetailService.fetchProduct and ShopConfigService.getShopConfiguration both work this way.

A service decides what its cache entries hold and what goes into the key. Rules for cached values covers when to cache the raw response instead of the mapped shape, how to keep customer data out of shared keys, and the TTLs.

Mappers are synchronous

A mapper turns a Storefront API response into a shared type, and it does nothing else. No async, no I/O, no cache reads. Every mapper in @scayle/storefront and every mapper in src/server/services/mappers/ holds to this, so you can test one without a browser or a running API.

A mapper takes the registry in its constructor and reaches a sibling through it. ShopConfigMapperService reads mappers.i18n once at construction and keeps it in a field, and the SDK's BasketMapper reads this.mappers.product at call time inside a method.

Output also depends on request state the mapper reads off this.context, such as the country that decides price formatting, and on overridable fields such as the low stock threshold. Same input plus same context gives the same result, which is what makes a mapper testable.

Keeping mapping in one layer is what makes the shape one decision in one place. A derived value such as isLowStock arrives finished in the browser, and every page that shows a product shows the same product. Extending the SDK walks through overriding a mapper and adding a field.

Controllers and procedures coordinate

A controller resolves services and mappers from the per-request registry, assembles the props, and returns them. It never instantiates a service, and it never calls the Storefront API itself.

Note the import paths. mountController and every Base*Controller come from @scayle/storefront/controllers, as does the BasketViewData type, while Inertia, Props, and Components come from the package root and Basket from @scayle/storefront/types. The package root exports no controllers, so importing BaseBasketController from @scayle/storefront fails to compile.

A controller that fetches a slow recommendation list and falls back to an empty array on error is still coordinating, and several of the page controllers do exactly that. What stays out is the domain work itself: deciding what a product costs, or what a basket contains, belongs to a service. When a private helper in a controller starts reshaping domain data, that logic wants to be in a mapper or a service instead.

oRPC procedures in src/server/api/ carry the actions that change data, and they reach the same registry through context.services and context.mappers. A procedure can also fetch and cache on its own: the two read procedures in src/server/api/cms.ts call context.storefront.storefrontAPI inside context.storefront.cache.getOrSet for the product queries a CMS component needs, because no service owns that query. Reach for a service first, and keep the fetch in the procedure only while it has one caller. See RPC API.

A page controller extends a base class from the SDK and implements getTemplate and getViewProps. Pages and Controllers covers the full set of hooks, deferred props, and server-only data, along with mounting a controller on a route.

Views render shared types

A Vue page declares its own props with defineProps, and reaches the props every page receives through usePage() when it needs one. It does not know which service produced the data or whether the response came from cache.

Mutations go through composables in src/client/composables/ that call useRpcClient(), and the Inertia router gets driven from both composables and a few pages. Checkout.vue calls router.reload to refresh its tokens, and ProductDetail.vue calls router.replace when you pick a variant. A page never fetches from the Storefront API and never reshapes a domain type. It renders what it receives and asks the server for more through an RPC call or a partial reload.

The shared types contract

Both sides read the domain types from @scayle/storefront/types, and src/shared/types/ is where your application adds to them. Alongside it, src/shared/routes.ts, src/shared/constants/, and src/shared/utils/ carry the other values both sides import. These rules keep the type contract honest.

Domain entities, not page bundles

A shared type is a domain entity such as BasketCost or PromotionReduction. Compose the props a page needs at the call site instead of declaring a PDPProps or BasketPayload wrapper. The application has none today, and PageProps is an alias for the SDK's SharedProps rather than a page-specific shape.

A field is not landed until a mapper sets it

Add the type field and update the mapper in the same merge request. Most shared type fields arrive through declare module augmentation, so TypeScript believes a field exists the moment you declare it, and a field no mapper sets ships as undefined on every request without an error from the mapper. Extending the SDK explains why.

No duplicated values in one interface

When two fields carry the same information, keep one. A field that holds a formatted string alongside its numeric source is fine, because the string is a rendering of the number and not a second copy of it. A price carries both its amount and the formatted string for it, and Pricing covers the rule for money on shared types.