Skip to main content
Alpha

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.

The concept map

Seven 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 last three explain the cross-cutting concerns every plugin shares — the local orchestrator, the telemetry it emits, and the pure-backend authentication seam.

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
  2. Contracts
  3. Plugin system
  4. Durability model
  5. Observability
  6. Aspire
  7. Auth model

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 and 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 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 for sagas (kv or prisma store) and the 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.
  • 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 page draws the exact line between real automatic traces and the no-op handler stubs.

Where to go next