DOCUMENTATION

Everything you need to understand and ship PipWeb.

Architecture, runtime, trust, migration, package distribution, deployment and release acceptance in one reference.

32documented topics
20framework packages
3primary surface types
0latest audit findings
Core architecture08 topics
Overview

What PipWeb is

PipWeb is PluginPip Ltd's full-stack TypeScript application framework. Its architectural centre is the Application Graph, not a filesystem router or a particular renderer.

The graph compiles capabilities, surfaces and flows into a validated model that can be inspected by the runtime, development tooling and machine interfaces.

React is the first web renderer and Node is the first runtime. Neither is intended to be the permanent architectural boundary of the framework.

  • Explicit over magical
  • TypeScript-first
  • Web standards at runtime boundaries
  • React-first with a renderer-independent core
  • Node-first with a deployment-independent core
  • Human and machine interfaces are peers
  • Security and observability are part of the architecture
Requirements

Current runtime and toolchain requirements

The current alpha line targets Node.js 24 or newer and a TypeScript-first workflow. PipWeb workspace package versions are synchronised.

  • Node.js 24+
  • TypeScript 5.9+
  • React 19 for the current web renderer
  • pnpm for framework workspace development
  • Private PluginPip package registry for current alpha packages
Create an app

Start from the production product starter

The product starter gives a new application a production-oriented baseline with canonical metadata, sitemap.xml, robots.txt, a web manifest and favicon support.

pipweb create my-product --template product
Application Graph

Model the application before the transport

The Application Graph is the compiled model of the whole application. It joins capabilities, surfaces and flows and validates their references before deployment.

The graph is inspectable architecture rather than framework convention hidden across folders.

  • Capabilities describe reusable business or infrastructure abilities
  • Surfaces expose capabilities to consumers
  • Flows compose capability actions into multi-step processes
  • Graph validation detects invalid references and unsafe exposure
Capabilities

Define what the application can do

Capabilities are version-controlled application dependencies, not runtime-installed plugins. They can describe actions, dependencies, trust requirements and entitlement boundaries.

const catalogue = defineCapability({
  name: "catalogue",
  provides: ["catalogue.read", "catalogue.search"],
  actions: [{
    name: "catalogue.search",
    trust: {
      actors: ["anonymous", "human", "agent", "service"],
      effect: "read",
      risk: "low",
      approval: "none",
      audit: "metadata"
    }
  }]
});
Surfaces

Expose one capability through multiple interfaces

A surface is an interface over a capability action. The same domain logic can power browser UI, JSON APIs and agent-facing actions without duplicating the capability itself.

  • web
  • API
  • agent
  • realtime
  • mobile
const api = defineSurface({
  name: "catalogue-api",
  kind: "api",
  route: "/api/products",
  method: "GET",
  capability: "catalogue",
  action: "catalogue.search"
});
Flows

Compose durable business work

Flows represent ordered capability actions for processes such as onboarding, quote-to-order, provisioning, invoicing or renewal.

The current runtime supports durable execution with retry, idempotency and compensation primitives.

  • Ordered capability actions
  • Retry policy
  • Idempotency
  • Compensation actions
  • Principal propagation
  • Entitlement propagation
  • Approval evidence propagation
Application definition

Compile the whole system into one definition

An application combines its capabilities, surfaces and flows into the graph consumed by the runtime.

export const application = defineApplication({
  name: "my-app",
  version: "0.1.0",
  capabilities: [catalogue],
  surfaces: [web, api, agent],
  flows: [enquiry]
});
Runtime & trust13 topics
Runtime

Bind graph intent to executable behaviour

Capability runtimes connect declared actions to executable handlers. Application runtime definitions then bind those capability runtimes to web, API or other surfaces.

PipWeb keeps execution context available to policy, entitlement, approval and audit layers rather than burying those concerns inside handlers.

React rendering

Server-render React without making React the architecture

PipWeb supports React server rendering, streaming SSR, hydration data and hashed client bundles while keeping capabilities and flows independent from React.

  • Server-rendered HTML
  • Streaming SSR
  • Hydration data
  • Hashed client bundles
  • Production asset references
SEO & metadata

Production document metadata is first-class

The React document layer supports production metadata and the SEO package generates machine-readable site files.

  • Canonical URLs
  • robots directives
  • Theme colour and web manifest
  • Icons and alternate-language links
  • Open Graph
  • Twitter/X cards
  • JSON-LD
  • sitemap.xml
  • robots.txt
HTTP primitives

Production web runtime behaviour

The runtime includes request parsing and delivery primitives expected by production applications.

  • JSON request parsing
  • URL-encoded forms
  • multipart/form-data
  • File uploads
  • Redirects
  • Server-Sent Events
  • Static asset delivery
  • HEAD support
  • ETags and 304 responses
  • Immutable caching
  • Byte ranges
WebSockets

Routed realtime endpoints

PipWeb can expose routed WebSocket endpoints with route parameters, origin policy and payload limits.

Sessions

Signed session cookies

The runtime can issue and verify HMAC-signed session cookies for applications that need server-managed session state.

HTTP security

Framework-level request protections

Security controls live at the runtime boundary so applications do not have to reimplement baseline protections per route.

  • Security headers
  • CORS
  • CSRF protection
  • Request limits
  • Correlated diagnostics
Trust contracts

Make authority machine-readable

Agent-exposed actions require explicit trust metadata. The runtime can resolve a principal, enforce actor and permission requirements and ask policy or approval layers whether execution may proceed.

  • Permitted actor kinds
  • Required permissions
  • Side-effect classification
  • Risk classification
  • Approval mode
  • Audit level
PipKey principals

Machine identity through PipKey

The PipKey integration can resolve agent principals from verified machine credentials. Verification can include audience, environment, scopes and linked entitlement evidence.

Admin PipKey credentials are rejected by default for agent execution.

Entitlements

Separate product entitlement from identity

Capability execution can declare organisation, product, module, grant and claim-constraint entitlement requirements independently from authentication and permissions.

  • Organisation entitlement
  • Product entitlement
  • Module entitlement
  • Grant requirements
  • Claim constraints
  • Fail-closed resolution
Human approval

Pause high-risk work before the handler runs

Actions declaring human approval can halt before execution. Approval evidence is tenant-scoped, single-use and bound to the exact request fingerprint.

Self-approval is forbidden by default and consumed approvals cannot be replayed.

  • Pending approval creation
  • Safe approval identifiers
  • Dedicated approval execution reference
  • Exact request fingerprint binding
  • Atomic approved-to-consumed transition
  • Cross-organisation concealment
  • Approval evidence attached to execution receipts
Audit receipts

Durable evidence without raw payload leakage

PipWeb emits privacy-minimised execution receipts with stable IDs and started, succeeded or failed lifecycle states.

A PostgreSQL-backed receipt store supports filtered lookup by organisation, principal, capability, action, status and time. Required receipt mode can fail closed before execution if durable evidence cannot be persisted.

Health & telemetry

Operate the application, not just the routes

The runtime exposes liveness, readiness and graph diagnostics and supports OpenTelemetry instrumentation.

  • /_pip/health
  • /_pip/ready
  • /_pip/graph
  • OpenTelemetry instrumentation
  • Correlated request diagnostics
Tooling, migration & production11 topics
CLI

Create, inspect, diagnose and migrate

The PipWeb CLI is the main developer entry point for creating applications, inspecting the compiled graph, running diagnostics and building migration plans.

  • create
  • doctor
  • inspect
  • audit
  • migrate next
pipweb create my-product --template product
pipweb doctor
pipweb inspect dist/app.js
pipweb audit dist/app.js
pipweb migrate next ../next-app --output ../pipweb-app
Static generation

Generate static web and API artifacts

PipWeb can generate static HTML and API artifacts and apply explicit cache and revalidation policies where an application does not need per-request execution.

Production adapters

Use infrastructure without making it the framework

PipWeb's production integrations are adapters rather than architectural dependencies.

  • PostgreSQL
  • Valkey
  • NATS
  • S3-compatible storage
  • OpenTelemetry
Deployment

Node and container deployment baseline

The current deployment baseline includes Node and Docker adapters. Additional deployment targets remain on the roadmap.

Next.js migration

Semantic migration rather than blind file copying

The migration planner understands common App Router and Pages Router structures, routes, handlers, layouts, server actions, metadata and framework-specific imports.

Generated migration output includes executable PipWeb scaffolding, source transformation, machine-readable reporting and explicit automatic/review/unsupported classification.

  • Static, dynamic and catch-all route translation
  • App Router and Pages Router discovery
  • Layouts and route handlers
  • Server-action discovery
  • Metadata and static-parameter detection
  • Revalidation and dynamic-rendering hints
  • Secret-safe .env handling
  • migration-report.json
  • MIGRATION.md
Next compatibility

Compatibility belongs to PipWeb, not Next.js internals

The PipWeb-owned compatibility package translates common Next.js application APIs while keeping migrated applications on PipWeb runtime ownership.

  • next/link
  • next/image
  • next/navigation
  • next/cache
  • next/server
  • App Router route handlers
  • Simple server actions
  • Pass-through middleware/proxy patterns
  • Nested layout composition
Package registry

Private PluginPip package distribution

Current alpha packages are distributed through the PluginPip Gitea npm registry. All @pluginpip/pipweb-* packages share the same framework version.

@pluginpip:registry=https://git.pluginpip.co.uk/api/packages/PluginPip/npm/
//git.pluginpip.co.uk/api/packages/PluginPip/npm/:_authToken=${GITEA_NPM_TOKEN}
Versioning

Synchronized Semantic Versioning

All PipWeb workspace packages use the same version. CI rejects malformed or divergent package versions.

Before 1.0, substantial capability additions still advance the minor line instead of hiding large changes in alpha counters.

  • alpha.N: active feature development
  • beta.N: feature-complete line under production testing
  • rc.N: release candidate
  • stable: prerelease suffix removed after acceptance
  • patch: backward-compatible hardening or fixes
pnpm version:check
pnpm version:set -- 0.3.0-alpha.10
Release acceptance

Ship only after the framework gates are green

PipWeb release acceptance is evidence-based. Package publication and consumer installation are part of the release proof, not an afterthought.

  • pnpm install --frozen-lockfile
  • pnpm version:check
  • pnpm build
  • pnpm typecheck
  • pnpm test
  • pipweb doctor
  • pipweb inspect
  • pipweb audit
  • Pack/publish synchronized packages
  • Verify a clean consumer install from the private registry
Supply chain

Release manifests, SBOM and provenance

PipWeb can produce release manifests, CycloneDX SBOMs and SLSA provenance to strengthen software supply-chain evidence.

Current status

What alpha.10 means today

PipWeb 0.3.0-alpha.10 is a production-capability alpha with a framework-level quality baseline. The core build, typecheck, tests, doctor, inspect and audit gates are green, all 20 packages are published privately, and a clean product-site consumer verifies critical CSS, metadata, accessibility defaults and production deployment output.

PluginPip-owned applications are being used as acceptance workloads before broader developer adoption.

  • Application Graph and runtime are operational
  • Web, API and agent surfaces are operational
  • Trust, entitlements, human approval and audit receipts are operational
  • Private package distribution is operational
  • Product-site starter is operational
  • Developer ergonomics, HMR, wider deployment adapters and broader compatibility testing remain active work
Next step

Keep the docs tied to the framework.

This reference is intentionally grounded in the current PipWeb source and release line. When capabilities change, the public documentation should move with the same release.