# Explanation Explanation pages are the **why** lane. They build the mental model: how NetScript is put together, why each boundary is shaped the way it is, and which trade-offs that shape buys you. Read them when you want to understand the framework, not when you are hunting for a specific command. NetScript is a **Deno-native, contracts-first backend framework**. Its design is governed by one thesis — *the published surface is the product* — and everything in this zone is a consequence of that single idea: types before implementation, a small predictable surface at every boundary, and durable behavior modeled as explicit state machines rather than scattered event handlers. > How this zone fits the others > > These pages are > > understanding-oriented > > . For a guided first path use the > > tutorials > > ; to get a concrete job done use the > > how-to guides > > ; to look up the exact symbols, ports, and signatures of any package use the generated > > reference > > ; and for a one-screen tour of each subsystem use the > > capabilities > > hubs. ## The concept map Eight topics, ordered from the broadest framing down to the individual subsystems. The first two explain the framework as a whole; the next two cover the durable runtime model; the following three explain the cross-cutting concerns every plugin shares — the local orchestrator, the telemetry it emits, and the pure-backend authentication seam. The last one steps outside the framework and compares its path to the frameworks you may be arriving from. [The NetScript architecture The published-surface thesis, the contracts-first workflow, the six package archetypes, and the publish gate that enforces all of it.](https://rickylabs.github.io/netscript/netscript/explanation/architecture/) [Contracts first How an oRPC contract flows from defineContract through implement() and a typed handler into a fully typed client, query layer, and island.](https://rickylabs.github.io/netscript/netscript/explanation/contracts/) [The plugin system How a plugin relates to its core package, what it contributes through its manifest, and how the host discovers it through generated registries.](https://rickylabs.github.io/netscript/netscript/explanation/plugin-system/) [Durability model Sagas as explicit state machines: correlation, the kv or prisma durable store, and compensation modeled as message-handler effects.](https://rickylabs.github.io/netscript/netscript/explanation/durability-model/) [Observability How automatic framework spans, scaffold handler telemetry, console logs, and Aspire collection fit together.](https://rickylabs.github.io/netscript/netscript/explanation/observability/) [The Aspire orchestrator The generated TypeScript AppHost, the resource graph (the Postgres container (the recommended engine) — or mysql / mssql via --db; sqlite is file-backed with no container — plus Redis and every *-api service), and the dashboard on :18888.](https://rickylabs.github.io/netscript/netscript/explanation/aspire/) [The pure-backend auth model Core defines the AuthBackendPort; backends are pure adapters; the plugin composes exactly one active backend. Why only kv-oauth is interactive.](https://rickylabs.github.io/netscript/netscript/explanation/auth-model/) [How NetScript's path compares What the canonical getting-started flows of Next.js, Nuxt, SvelteKit, Laravel, and Rails teach first, where NetScript's ordering diverges and why, and where those peers are ahead today.](https://rickylabs.github.io/netscript/netscript/explanation/compared/) ## A suggested reading order These pages stand alone, but they compound. If you are new to the design, read them top to bottom: the architecture page sets the vocabulary the rest assume, and the auth model is easiest to grasp once you already understand plugins and ports. 1. [Architecture](https://rickylabs.github.io/netscript/netscript/explanation/architecture/) 2. [Contracts](https://rickylabs.github.io/netscript/netscript/explanation/contracts/) 3. [Plugin system](https://rickylabs.github.io/netscript/netscript/explanation/plugin-system/) 4. [Durability model](https://rickylabs.github.io/netscript/netscript/explanation/durability-model/) 5. [Observability](https://rickylabs.github.io/netscript/netscript/explanation/observability/) 6. [Aspire](https://rickylabs.github.io/netscript/netscript/explanation/aspire/) 7. [Auth model](https://rickylabs.github.io/netscript/netscript/explanation/auth-model/) 8. [How the path compares](https://rickylabs.github.io/netscript/netscript/explanation/compared/) ## Themes that recur across every page A handful of ideas surface again and again. Recognizing them early makes the rest of this zone read as one coherent argument rather than seven separate articles. - **Contracts before implementation.** Every subsystem starts from a schema and type contract — an oRPC contract for a service, a `defineSaga` definition for a workflow, an `AuthBackendPort` for an auth adapter — and the implementation is written to satisfy it. The [architecture](https://rickylabs.github.io/netscript/explanation/architecture/) and [contracts](https://rickylabs.github.io/netscript/explanation/contracts/) pages establish this; everything else applies it. - **Ports own the seam; adapters stay swappable.** A package owns the *port* and wires one default adapter through a `createX()` factory, while technology-specific adapters and in-memory testing helpers live behind their own subpaths. The [auth model](https://rickylabs.github.io/netscript/explanation/auth-model/) is the sharpest example — `AuthBackendPort` is defined once in core and satisfied by three independent backends. - **Durable state is explicit.** Long-running behavior is a named state machine with a persistence backend, not an implicit ladder of callbacks. See [durable workflows](https://rickylabs.github.io/netscript/explanation/durability-model/) for sagas (`kv` or `prisma` store) and the [auth model](https://rickylabs.github.io/netscript/explanation/auth-model/) for durable `auth.*` events. - **Plugins extend without redefining.** First-party plugins under `plugins/*` re-export their core package's contract and contribute service entrypoints, runtime declarations, and schema fragments — covered in the [plugin model](https://rickylabs.github.io/netscript/explanation/plugin-system/). - **Alpha reality stated plainly.** Where the scaffold ships a stub — the worker handler trace helpers, the streams *manifest* helpers, the absent auth audit surface — these pages say so plainly. The [observability](https://rickylabs.github.io/netscript/explanation/observability/) page draws the exact line between real automatic traces and the no-op handler stubs. > Where to verify a claim > > Every command, port, and import specifier in this zone is grounded in the generated > > reference > > (one page per published package). When an explanation page names a symbol, follow its link to > > reference// > > for the exact signature — the reference is the single source of truth, and these pages never duplicate it. ## Where to go next - Start with [The NetScript architecture](https://rickylabs.github.io/netscript/explanation/architecture/) for the framework-wide model and vocabulary. - Jump straight to [The pure-backend auth model](https://rickylabs.github.io/netscript/explanation/auth-model/) if you are evaluating NetScript's authentication seam. - Cross over to the [capabilities](https://rickylabs.github.io/netscript/capabilities/) hubs for a per-subsystem tour with headline APIs, or to the [reference](https://rickylabs.github.io/netscript/reference/) for exact symbols.