Architecture Principles
The Storefront Application V3 is built so that your team spends its time on what makes your shop different. SCAYLE keeps the commerce logic that every shop shares in versioned packages, and your team owns the code that makes your shop yours. This page explains the principles behind that split, what each one gives your team, and what it costs. Architecture shows how the application puts them into practice.
| Principle | What it means for your team | What you give up |
|---|---|---|
| Shared commerce logic | The commerce logic every shop needs, such as basket handling and promotion rules, comes from SCAYLE packages and the Commerce Engine. Your team builds on it instead of writing it from scratch. | The freedom to rebuild that logic your own way. Your team extends it. |
| Commerce facts stay in the Commerce Engine | Prices, stock, promotion rules, and checkout settings are decided in the SCAYLE Commerce Engine and the SCAYLE Panel. Business users change them without a code change. | Your code presents these values and does not decide them. |
| Users see what they need first | A page shows its essential content right away and loads the slower parts afterward. | Your team decides for each page what counts as essential. |
| Actions have their own path | Adding an item to the basket or applying a promotion code is a typed request of its own, separate from loading a page. | A little more structure than requests sent from any component. |
| One place for each customization | Shops built on the Storefront Application V3 change the same things in the same place. | A developer learns an extension point before using it. |
| Developer experience first | Mainstream open source tools, a CLI that sets up a project from your shop, tools that show what a page received and sent, and instruction files for AI coding agents. | Your team works within the conventions of this stack. |
| Your code is yours | Every file under src/ in your fork is yours to change, and SDK updates do not rewrite it. | Fixes to the application code do not reach your fork automatically. |
Shared commerce logic, your own shop code
Basket handling and promotion rules work the same in every shop. SCAYLE builds and maintains that logic once and ships it as versioned packages, and the Commerce Engine decides the values. Your team extends it with what is specific to your shop: its branding, how it presents its products, and its own pages. Extending the SDK shows how your team adds its own code to the shared logic.
Commerce facts stay in the Commerce Engine
The Storefront API and the SCAYLE Panel decide prices, stock, promotion rules, and order state, not your storefront. A pricing rule is a Panel change, not a code change. Checkout follows the same principle. Payment methods, guest checkout, and checkout fields are Panel settings, and the SCAYLE Checkout component runs the checkout flow. Business users change these settings without waiting for a code change. Your code presents the values and has no hook into the steps of the flow. This keeps time-sensitive decisions with the business team and keeps your code focused on feature work. See What you own and what SCAYLE owns and the Checkout page.
Users see what they need first
On a product page, a user needs the price, the images, and the size options right away. The Storefront Application V3 renders that content on the server and sends it as soon as it is ready. Slower content that is not needed immediately, such as recommended products further down the page, loads afterward. Your team decides for each page what counts as essential. See Pages and Controllers.
Actions have their own path
Adding an item to the basket and applying a promotion code are actions that a user triggers on purpose. They run as typed requests of their own, separate from loading a page. Your team can tell from where something is built whether it shows data or acts on it. See RPC API.
One place for each customization
Your team changes how a product displays or how a step behaves by extending a documented default, not by writing the behavior from nothing. Shops built on the Storefront Application V3 customize the same things in the same place, so a developer who has worked on one shop knows where to look in the next one. See Layers and Data Flow and Project Structure.
Developer experience first
The application is built on mainstream open source tools with public documentation. The linter enforces the import rules between the server and the client, and the actions the browser sends to the server are typed. The Storefront CLI sets up a project from your shop's data, Storefront DevTools show the Inertia.js visits, page props, and oRPC calls of a page while your team builds, and the project ships instruction files and skills for AI coding agents. The cost is that your team works within the conventions of this stack, and replacing one of its tools is a real cost. See Tech Stack.
Your code is yours
Every file under src/ in your fork is yours to change, and no SDK release rewrites one of them. The SDK packages arrive through version bumps. A change that you express as an extension of an SDK class keeps receiving SDK upgrades. The Storefront Application V3 is licensed under BSD 3-Clause and the SDK packages under MIT.