# Live Dashboard

An order queue goes wrong quietly. The screen your fulfillment team watches shows five-minute-old rows, so the packing station ships an order the customer cancelled three minutes ago, and a payment that failed at 14:02 sits looking like `processing` until someone thinks to hit refresh. The usual fix — poll harder — just trades staleness for load and still leaves a gap for the next missed cancellation.

This track builds the alternative end to end: a real-time operations dashboard for an order queue. By the last chapter you will have a table that updates **live** in the browser — no manual refresh, no polling loop, no hand-rolled WebSocket — fed by the full NetScript data spine, from a typed contract on the backend to a durable change-stream on the frontend. It is the same durable-stream seam the streams plugin scaffolds into a workspace for notification fan-out — here, pointed at your orders.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/01-scaffold/)
2. [2 · Contract to service](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/02-contract-to-service/)
3. [3 · Cache-first query](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/03-sdk-cache-first-query/)
4. [4 · definePage + island](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/04-definePage-QueryIsland/)
5. [5 · Live stream](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/05-live-stream/)
6. [6 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/06-deploy/)

## What you will build

A `my-dashboard/` Fresh workspace whose home screen is the order queue described above, fed by a live stream subscription. You scaffold a fresh NetScript project, expose an `orders` read-model through a typed oRPC service, wire a cache-first SDK query layer, render the queue with NetScript's `definePage` page builder and a hydrated TanStack Query island, then subscribe it to a durable change-stream so the server can push updates into an open page — the point where the refresh button stops mattering. The final chapter runs the whole graph locally under Aspire. This is a learning track: the same project grows chapter by chapter, so do them in order.

## Before you begin

You need a working local toolchain — the same one every NetScript tutorial assumes. Confirm Deno, the Aspire CLI, and Docker are on your `PATH`:

```sh
deno --version && aspire --version && docker info
```

You should see a Deno 2.x version, an Aspire CLI version, and Docker engine details (not a connection error). If any are missing, the [quickstart](https://rickylabs.github.io/netscript/quickstart/) walks through installing them. Install the NetScript CLI once:

```sh
deno install --global --allow-all --name netscript jsr:@netscript/cli@0.0.6
```

> New to NetScript? Walk the main ladder first
>
> This track assumes you are comfortable with the contract-first service loop. If
>
> defineService
>
> and oRPC contracts are new, do the
>
> Quickstart
>
> and the
>
> Storefront catalog-service chapter
>
> first — they move slower. This track moves faster and goes deeper on the Fresh consumer surface.

## The arc: contract → client → query → island → stream

NetScript's signature spine carries one shape of data from the database all the way to a live cell in the browser, type-checked at every hop. Each chapter adds exactly one link:

[1 · Scaffold the workspace  Create `my-dashboard/` with `netscript init`, tour the Fresh app, and boot it under Aspire. You end with a running frontend on the app port and the Aspire dashboard on :18888.](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/01-scaffold/)

[2 · A typed read-model service  Define an `orders` oRPC contract with `.route().input().output()` and serve it with `defineService`. This is the data your dashboard reads.](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/02-contract-to-service/)

[3 · SDK client + cache-first query  Build a typed `createServiceClient` and a `createQueryFactories` query layer with KV-backed stale-while-revalidate. Service discovery resolves the URL for you.](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/03-sdk-cache-first-query/)

[4 · definePage + QueryIsland  Render the table with NetScript's `definePage` builder — the layer / partial / island triad — and hydrate a TanStack Query island for client-side reads and optimistic mutations.](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/04-definePage-QueryIsland/)

[5 · Go live with StreamDB  Replace polling with a durable change-stream: `createSagasStreamDB` feeds `useLiveQuery`, and rows arrive over the open subscription whenever the sagas mirror publishes — today, once per service start.](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/05-live-stream/)

[6 · Run it all under Aspire  Bring the whole graph up locally — service, Fresh app, streams runtime, Postgres (the default; swap `--db` for `mysql` / `mssql` / `sqlite` at scaffold time), Redis — with one `aspire start`. Clear about what local orchestration is and is not.](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/06-deploy/)

> Where to look things up
>
> This track teaches the path. For exact symbols and signatures, the
>
> reference
>
> is generated from source and always current — the
>
> fresh
>
> ,
>
> sdk
>
> ,
>
> service
>
> , and
>
> streams
>
> units back the chapters here. For the reasoning behind contracts and durability, read the
>
> explanation
>
> pages.

## What you built

By the end of this track you will own an order queue your operations team can act on without second-guessing it — and, more importantly, the full NetScript read spine that powers it, from contract to durable stream. Every hop is typed off the same contract, so the row a packer sees is the row the service wrote.

[Tutorials](https://rickylabs.github.io/netscript/netscript/tutorials/) [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/01-scaffold/)

After this track, keep building in **Build › [Web Layer](https://rickylabs.github.io/netscript/web-layer/)** — the guides and recipes there pick up where these chapters stop.