Wayfinder 0.9.2

<picture> <source media="(prefers-color-scheme: dark)" srcset="assets/wordmark-dark.png"> <img src="assets/wordmark-light.png" alt="Wayfinder" height="56"> </picture>

A service blueprint / service-design engine: domain model, calculation engine, state-machine engine, and a compiled visual editor web component. Framework-agnostic, with no Umbraco, no ASP.NET Core MVC, and no hosting assumptions baked in.

The domain model is the service blueprint as the Nielsen Norman Group defines it: a user journey laid out across customer actions, frontstage, backstage, and support processes, divided by the lines of interaction, visibility, and internal interaction. Wayfinder makes that model executable, and delivers journeys to GDS Service Standard practice with the real GOV.UK Design System.

Wayfinder was extracted from Umbraco Prism, which is now a consumer of these packages rather than their owner. A host application, Umbraco-based or otherwise, layers its own tenancy, auth, and rendering opinions on top. Wayfinder.Umbraco is the Umbraco-hosted implementation Prism itself uses.

How it fits together

graph LR
  WF["Wayfinder<br/>core engine<br/>(this repo)"] --> WFU["Wayfinder.Umbraco<br/>CMS binding"]
  WFU --> PRISM["Umbraco Prism<br/>multi-tenant host<br/>(OIDC, branding)"]

• Wayfinder (this repo) is the framework-agnostic core: the domain model, the calculation engine, and the state-machine engine. No Umbraco, no hosting assumptions.
• Wayfinder.Umbraco is the Umbraco host: a DB-backed store, Block Grid blocks, an authoring UI, and GOV.UK rendering.
• Umbraco Prism is the reference consumer for multi-tenancy and branding — UmbracoPrism.Core carries no service-design opinion of its own.

Quickstart

dotnet add package Wayfinder.Engine

Seed a blueprint (a JSON file — see docs/guides/reference-service-blueprint-contract.md for the full schema):

// blueprints/apply-for-a-licence.json
{
  "definitionKey": "apply-for-a-licence",
  "displayName": "Apply for a licence",
  "version": 1,
  "initialStage": "start",
  "requestPolicy": "single",
  "queues": [ { "key": "citizen", "displayName": "Citizen", "actor": "citizen" } ],
  "stages": [
    {
      "stageKey": "start",
      "displayName": "Your details",
      "queueKey": "citizen",
      "components": [ { "type": "text", "fieldKey": "fullName", "label": "Full name", "required": true } ],
      "routes": [ { "id": "start--submit--done", "target": "done", "trigger": "submit" } ]
    },
    { "stageKey": "done", "displayName": "Application submitted", "queueKey": "citizen", "components": [ { "type": "panel", "heading": "Application complete" } ] }
  ]
}

Register the engine and round-trip an instance:

using Wayfinder.Engine.Extensions;

builder.Services.AddProcessManager("blueprints"); // folder containing the JSON above

using Wayfinder.Models.ServiceDesign;

var envelope = processManager.GetCurrent(
    blueprintKey: "apply-for-a-licence", tenantId: "default", userId: "user-1",
    accessProfile: ActorProfile.UnrestrictedOwner);
// envelope.ResponseState == "render" — envelope.Render.Components has the "Your details" fields

var advanced = processManager.Advance(
    instanceId: envelope.InstanceId, tenantId: "default", userId: "user-1",
    accessProfile: ActorProfile.UnrestrictedOwner, action: "submit", expectedStateVersion: envelope.StateVersion,
    fieldValues: new Dictionary<string, object?> { ["fullName"] = "Ada Lovelace" });
// advanced.Render.StateDisplayName == "Application submitted"

That's the whole engine surface a host needs: GetCurrent to render the current step, Advance to submit it. Wayfinder.Umbraco wraps exactly these two calls behind a Block Grid block; see its own README for the CMS-hosted version.

See it running

Wayfinder.AppHost + Wayfinder.ReferenceApp is a small, self-contained .NET Aspire host in this repo, with every package wired together, real GOV.UK Design System rendering, a demo login, and a seeded "apply for a licence to hold a juggling event" journey. It's the fastest way to see what a working Wayfinder host actually looks like, and exactly how little wiring a real host (like Wayfinder.Umbraco) collapses into. Run it with dotnet run --project Wayfinder.AppHost, or the "C#: Aspire (Full Stack)" launch config in VS Code. See docs/guides/reference-app.md for what it implements, how the demo blueprint is seeded from JSON and only saved in memory, and what a real host does differently.

Packages

Core

Surfaces — HTTP glue a host maps into its own pipeline

Rendering & Editor

The service blueprint model

Wayfinder implements the Nielsen Norman Group service blueprint (Sarah Gibbons, 2017) as a runnable artefact. In that model a user's journey is laid out across horizontal lanes, divided by the lines of interaction, visibility, and internal interaction. Those lanes are a blueprint's queues, one for each team or system that does the work. A stage is a step in the journey. Every stage sits in a queue, and the queue is what places it in a lane, so a stage is a stage whether it happens frontstage or backstage. A gateway is the route from one stage to the next, from any lane to any lane. Alongside the route a gateway carries the declarative rules for it: whether to split or join, waiting information, and the conditions that choose a path. Support Systems is NN/g's support-processes lane made first-class.

The model is the Nielsen Norman Group service blueprint (Sarah Gibbons, 2017). See the article for Gibbons' own worked example.

A ServiceBlueprint describes a journey as queues (named work queues), stages (each owning its own routes), and gateways (first-class Split/Join routing nodes that a stage's routes always target, never another stage directly). See docs/guides/reference-service-blueprint-contract.md for the full authoring schema, and docs/guides/calculation-language.md for the declarative expression language used in calculations and showWhen.

AI-ready authoring

Service blueprint authoring is exposed to AI agents (Claude Code or any MCP client) the same way it's exposed to a human editor: as a toolkit a host app wires into its own pipeline. Wayfinder.Engine.Api and Wayfinder.Engine.Mcp map the same list/read/validate/save/simulate operations as REST and MCP-over-HTTP respectively, both calling straight into a host's live Wayfinder.Engine in-process. See docs/guides/ai-service-blueprint-authoring.md.

Building

dotnet build Wayfinder.slnx
dotnet pack Wayfinder.slnx

License

MIT. See LICENSE.