# Build a storefront backend This track is a project, not a tour. Across seven chapters you build a small e-commerce storefront — a products catalog, a cart, a durable checkout, a shipping webhook, and a storefront page — in one workspace that grows chapter by chapter. It is the same spine the NetScript playground runs, re-themed as a shop, so every pattern you learn here is one the framework's own example app uses in anger. The differentiator this track proves is **one typed contract, honored from the database to the button**: the oRPC schema you write once is the same object the server handler validates against, the same one a page's query and checkout mutation are typed from, so a wrong field is a compile error, not a 2 a.m. incident. **What this replaces:** the hand-maintained REST-plus-fetch-wrapper-plus-DTO stack where the client's idea of a cart and the server's idea of a cart are two files that drift until production catches them apart. 1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/01-scaffold/) 2. [2 · Catalog service](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/02-catalog-service/) 3. [3 · Cart contracts](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/03-cart-contracts/) 4. [4 · Checkout saga](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/04-checkout-saga/) 5. [5 · Shipping webhook](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/05-shipping-webhook/) 6. [6 · Storefront UI](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/06-storefront-ui/) 7. [7 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/07-deploy/) ## What you will build A working storefront backend called `my-shop/`: a typed `products` catalog service backed by Postgres, a `cart` domain defined contract-first, a durable `checkout` saga that survives restarts and compensates on failure, and an HMAC-verified shipping webhook that hands inbound provider events to a background job. By the last chapter the whole thing runs on your machine under one orchestrator, visible in a single dashboard. The arc is deliberate. It teaches NetScript's central opinion — **the oRPC contract is the single source of truth** — and then shows what that buys you once the happy path needs to survive money changing hands: durable workflows and verified webhooks make checkout reliable instead of hopeful. ## The shape of the app [Catalog → cart → checkout → shipping Products live in a typed service. A cart contract models a new domain. Checkout is a durable saga with a compensation branch. Shipping arrives as a verified webhook that enqueues a job. Each piece is one chapter.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/02-catalog-service/) [Contract-first, everywhere Every service surface is an `@orpc/contract` route with Zod input/output schemas — many of them generated from Prisma. Write the schema once and the server handler, the typed client, and the OpenAPI projection all agree.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/02-catalog-service/) [Durable by design Checkout is not a one-shot call — it is a state machine with `defineSaga` that checkpoints its state, reacts to payment and inventory messages, and runs a compensation path when a step fails.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/04-checkout-saga/) ## Who this is for You are comfortable with TypeScript and have used Deno at least a little. You do not need prior NetScript experience — chapter 1 starts from an empty folder — but if you have never run the framework locally, skim the [Quickstart](https://rickylabs.github.io/netscript/quickstart/) first; it covers the same scaffold at a gentler pace. This track moves faster and stays on the storefront domain the whole way. You also do not need to read the whole framework before you start. Each chapter introduces exactly one new capability, grounds it in real running code, and proves it with a command whose output you can check. ## The seven chapters [1 · Scaffold Create `my-shop/` with the `netscript` CLI and boot it under Aspire. Postgres (the default; swap `--db postgres` for `mysql`, `mssql`, or `sqlite`), the Redis cache, and your service come up together; the dashboard answers on :18888.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/01-scaffold/) [2 · Catalog service Define a typed `products` contract whose schemas come from Prisma, implement the handlers against a Postgres-backed database client, and serve it with `defineService` (on port 3001 in this tutorial; note that each scaffolded project is allocated its own randomized high-range ports).](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/02-catalog-service/) [3 · Cart contracts Model a brand-new `cart` domain contract-first — list, getById, create, update — with shared typed errors, then derive a fully typed client from it. No handler guesswork.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/03-cart-contracts/) [4 · Checkout saga Turn checkout into a durable workflow with `defineSaga`: a state machine that walks order → payment → inventory → shipment and compensates when a step fails.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/04-checkout-saga/) [5 · Shipping webhook Accept an HMAC-verified shipping/payment webhook with `defineWebhook` and hand each inbound event to a background job with `enqueueJob`.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/05-shipping-webhook/) [6 · Storefront UI Put a face on the backend: a typed cart route with `createRouteReference`, a catalog query and a checkout mutation driven through `createServiceClient` → `createQueryFactories` in a Fresh island. The typed contract, honored all the way to the button.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/06-storefront-ui/) [7 · Deploy Run the whole storefront locally under one `aspire start` — every service, plugin API, and background processor in one resource graph, observable from the dashboard. The local topology, not a cloud deployer.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/07-deploy/) > One workspace, carried forward > > This is a tutorial track: state compounds. The > > my-shop/ > > workspace you create in chapter 1 is the same one you finish in chapter 7 — each chapter begins by checking the project state the previous one left, and each "What you built" feeds the next chapter's objective. Work the chapters in order. ## Start the build [Tutorials](https://rickylabs.github.io/netscript/netscript/tutorials/) [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/01-scaffold/) After this track, keep building in **Build › [Services & SDK](https://rickylabs.github.io/netscript/services-sdk/)** — the guides and recipes there pick up where these chapters stop.