DFE-Digital · gunndabad · Nov 21, 2025
diff --git a/TeachingRecordSystem/src/TeachingRecordSystem.SupportUi/LinkGeneratorExtensions.cs b/TeachingRecordSystem/src/TeachingRecordSystem.SupportUi/LinkGeneratorExtensions.cs
@@ -10,7 +10,7 @@ public static string GetRequiredPathByPage(this LinkGenerator linkGenerator, str
 
         if (journeyInstanceId?.UniqueKey is string journeyInstanceUniqueKey)
         {
-            url = QueryHelpers.AddQueryString(url, WebCommon.FormFlow.Constants.UniqueKeyQueryParameterName, journeyInstanceUniqueKey);
+            url = QueryHelpers.AddQueryString(url, Constants.UniqueKeyQueryParameterName, journeyInstanceUniqueKey);
         }
 
         return url;

diff --git a/...dSystem/src/TeachingRecordSystem.SupportUi/Pages/Alerts/AddAlert/AddAlertLinkGenerator.cs b/...dSystem/src/TeachingRecordSystem.SupportUi/Pages/Alerts/AddAlert/AddAlertLinkGenerator.cs
@@ -5,32 +5,32 @@ public class AddAlertLinkGenerator(LinkGenerator linkGenerator)
     public string Index(Guid personId, JourneyInstanceId? journeyInstanceId) =>
         linkGenerator.GetRequiredPathByPage("/Alerts/AddAlert/Index", routeValues: new { personId }, journeyInstanceId: journeyInstanceId);
 
-    public string Type(Guid personId, JourneyInstanceId journeyInstanceId, bool? fromCheckAnswers = null) =>
-        linkGenerator.GetRequiredPathByPage("/Alerts/AddAlert/Type", routeValues: new { personId, fromCheckAnswers }, journeyInstanceId: journeyInstanceId);
+    public string Type(Guid personId, JourneyInstanceId journeyInstanceId, string? returnUrl = null) =>
+        linkGenerator.GetRequiredPathByPage("/Alerts/AddAlert/Type", routeValues: new { personId, returnUrl }, journeyInstanceId: journeyInstanceId);
 
     public string TypeCancel(Guid personId, JourneyInstanceId journeyInstanceId) =>
         linkGenerator.GetRequiredPathByPage("/Alerts/AddAlert/Type", "cancel", routeValues: new { personId }, journeyInstanceId: journeyInstanceId);
 
-    public string Details(Guid personId, JourneyInstanceId journeyInstanceId, bool? fromCheckAnswers = null) =>
-        linkGenerator.GetRequiredPathByPage("/Alerts/AddAlert/Details", routeValues: new { personId, fromCheckAnswers }, journeyInstanceId: journeyInstanceId);
+    public string Details(Guid personId, JourneyInstanceId journeyInstanceId, string? returnUrl = null) =>
+        linkGenerator.GetRequiredPathByPage("/Alerts/AddAlert/Details", routeValues: new { personId, returnUrl }, journeyInstanceId: journeyInstanceId);
 
     public string DetailsCancel(Guid personId, JourneyInstanceId journeyInstanceId) =>
         linkGenerator.GetRequiredPathByPage("/Alerts/AddAlert/Details", "cancel", routeValues: new { personId }, journeyInstanceId: journeyInstanceId);
 
-    public string Link(Guid personId, JourneyInstanceId journeyInstanceId, bool? fromCheckAnswers = null) =>
-        linkGenerator.GetRequiredPathByPage("/Alerts/AddAlert/Link", routeValues: new { personId, fromCheckAnswers }, journeyInstanceId: journeyInstanceId);
+    public string Link(Guid personId, JourneyInstanceId journeyInstanceId, string? returnUrl = null) =>
+        linkGenerator.GetRequiredPathByPage("/Alerts/AddAlert/Link", routeValues: new { personId, returnUrl }, journeyInstanceId: journeyInstanceId);
 
     public string LinkCancel(Guid personId, JourneyInstanceId journeyInstanceId) =>
         linkGenerator.GetRequiredPathByPage("/Alerts/AddAlert/Link", "cancel", routeValues: new { personId }, journeyInstanceId: journeyInstanceId);
 
-    public string StartDate(Guid personId, JourneyInstanceId journeyInstanceId, bool? fromCheckAnswers = null) =>
-        linkGenerator.GetRequiredPathByPage("/Alerts/AddAlert/StartDate", routeValues: new { personId, fromCheckAnswers }, journeyInstanceId: journeyInstanceId);
+    public string StartDate(Guid personId, JourneyInstanceId journeyInstanceId, string? returnUrl = null) =>
+        linkGenerator.GetRequiredPathByPage("/Alerts/AddAlert/StartDate", routeValues: new { personId, returnUrl }, journeyInstanceId: journeyInstanceId);
 
     public string StartDateCancel(Guid personId, JourneyInstanceId journeyInstanceId) =>
         linkGenerator.GetRequiredPathByPage("/Alerts/AddAlert/StartDate", "cancel", routeValues: new { personId }, journeyInstanceId: journeyInstanceId);
 
-    public string Reason(Guid personId, JourneyInstanceId journeyInstanceId, bool? fromCheckAnswers = null) =>
-        linkGenerator.GetRequiredPathByPage("/Alerts/AddAlert/Reason", routeValues: new { personId, fromCheckAnswers }, journeyInstanceId: journeyInstanceId);
+    public string Reason(Guid personId, JourneyInstanceId journeyInstanceId, string? returnUrl = null) =>
+        linkGenerator.GetRequiredPathByPage("/Alerts/AddAlert/Reason", routeValues: new { personId, returnUrl }, journeyInstanceId: journeyInstanceId);
 
     public string ReasonCancel(Guid personId, JourneyInstanceId journeyInstanceId) =>
         linkGenerator.GetRequiredPathByPage("/Alerts/AddAlert/Reason", "cancel", routeValues: new { personId }, journeyInstanceId: journeyInstanceId);

diff --git a/...ingRecordSystem/src/TeachingRecordSystem.SupportUi/Pages/Alerts/AddAlert/AddAlertState.cs b/...ingRecordSystem/src/TeachingRecordSystem.SupportUi/Pages/Alerts/AddAlert/AddAlertState.cs
@@ -1,17 +1,16 @@
-using System.Diagnostics.CodeAnalysis;
-using System.Text.Json.Serialization;
 using TeachingRecordSystem.SupportUi.Pages.Shared.Evidence;
-
 namespace TeachingRecordSystem.SupportUi.Pages.Alerts.AddAlert;
 
-public class AddAlertState : IRegisterJourney
+public class AddAlertState : IRegisterJourney, IJourneyWithSteps
 {
     public static JourneyDescriptor Journey => new(
         JourneyNames.AddAlert,
         typeof(AddAlertState),
         requestDataKeys: ["personId"],
         appendUniqueKey: true);
 
+    public required JourneySteps Steps { get; init; }
+
     public Guid? AlertTypeId { get; set; }
 
     public string? AlertTypeName { get; set; }
@@ -32,14 +31,14 @@ public class AddAlertState : IRegisterJourney
 
     public EvidenceUploadModel Evidence { get; set; } = new();
 
-    [JsonIgnore]
-    [MemberNotNullWhen(true, nameof(AlertTypeId), nameof(Details), nameof(StartDate))]
-    public bool IsComplete =>
-        AlertTypeId.HasValue &&
-        AddLink.HasValue &&
-        StartDate.HasValue &&
-        AddReason.HasValue &&
-        HasAdditionalReasonDetail is bool hasDetail &&
-        (!hasDetail || AddReasonDetail is not null) &&
-        Evidence.IsComplete;
+}
+public class AddAlertStateJourneyStateFactory(SupportUiLinkGenerator linkGenerator) : IJourneyStateFactory<AddAlertState>
+{
+    public Task<AddAlertState> CreateAsync(CreateJourneyStateContext context)
+    {
+        var personId = context.HttpContext.GetCurrentPersonFeature().PersonId;
+        var firstStep = new JourneyStep(linkGenerator.Alerts.AddAlert.Index(personId, context.InstanceId));
+        var state = new AddAlertState { Steps = JourneySteps.Create(firstStep) };
+        return Task.FromResult(state);
+    }
 }
diff --git a/...RecordSystem/src/TeachingRecordSystem.SupportUi/Pages/Alerts/AddAlert/CheckAnswers.cshtml b/...RecordSystem/src/TeachingRecordSystem.SupportUi/Pages/Alerts/AddAlert/CheckAnswers.cshtml
@@ -1,11 +1,13 @@
-@page "/alerts/add/check-answers/{handler?}"
+@page "/alerts/add/check-answers"
 @model TeachingRecordSystem.SupportUi.Pages.Alerts.AddAlert.CheckAnswersModel
 @{
     ViewBag.Title = "Check details before adding alert";
+
+    var returnUrl = Request.GetEncodedPathAndQuery();
 }
 
 @section BeforeContent {
-    <govuk-back-link href="@LinkGenerator.Alerts.AddAlert.Reason(Model.PersonId, Model.JourneyInstance!.InstanceId)">Back</govuk-back-link>
+    <govuk-back-link href="@Model.JourneyInstance!.GetPreviousStepUrl()">Back</govuk-back-link>
 }
 
 <div class="govuk-grid-row">
@@ -19,14 +21,14 @@
                     <govuk-summary-list-row-key>Alert type</govuk-summary-list-row-key>
                     <govuk-summary-list-row-value>@Model.AlertTypeName</govuk-summary-list-row-value>
                     <govuk-summary-list-row-actions>
-                        <govuk-summary-list-row-action href="@LinkGenerator.Alerts.AddAlert.Type(Model.PersonId, Model.JourneyInstance!.InstanceId, fromCheckAnswers: true)" visually-hidden-text="alert type">Change</govuk-summary-list-row-action>
+                        <govuk-summary-list-row-action href="@LinkGenerator.Alerts.AddAlert.Type(Model.PersonId, Model.JourneyInstance!.InstanceId, returnUrl)" visually-hidden-text="alert type">Change</govuk-summary-list-row-action>
                     </govuk-summary-list-row-actions>
                 </govuk-summary-list-row>
                 <govuk-summary-list-row>
                     <govuk-summary-list-row-key>Details</govuk-summary-list-row-key>
                     <govuk-summary-list-row-value use-empty-fallback>@Html.ConvertNewlinesToLineBreaks(Model.Details)</govuk-summary-list-row-value>
                     <govuk-summary-list-row-actions>
-                        <govuk-summary-list-row-action href="@LinkGenerator.Alerts.AddAlert.Details(Model.PersonId, Model.JourneyInstance!.InstanceId, fromCheckAnswers: true)" visually-hidden-text="details">Change</govuk-summary-list-row-action>
+                        <govuk-summary-list-row-action href="@LinkGenerator.Alerts.AddAlert.Details(Model.PersonId, Model.JourneyInstance!.InstanceId, returnUrl)" visually-hidden-text="details">Change</govuk-summary-list-row-action>
                     </govuk-summary-list-row-actions>
                 </govuk-summary-list-row>
                 <govuk-summary-list-row>
@@ -42,14 +44,14 @@
                         }
                     </govuk-summary-list-row-value>
                     <govuk-summary-list-row-actions>
-                        <govuk-summary-list-row-action href="@LinkGenerator.Alerts.AddAlert.Link(Model.PersonId, Model.JourneyInstance!.InstanceId, fromCheckAnswers: true)" visually-hidden-text="link">Change</govuk-summary-list-row-action>
+                        <govuk-summary-list-row-action href="@LinkGenerator.Alerts.AddAlert.Link(Model.PersonId, Model.JourneyInstance!.InstanceId, returnUrl)" visually-hidden-text="link">Change</govuk-summary-list-row-action>
                     </govuk-summary-list-row-actions>
                 </govuk-summary-list-row>
                 <govuk-summary-list-row>
                     <govuk-summary-list-row-key>Start date</govuk-summary-list-row-key>
                     <govuk-summary-list-row-value>@Model.StartDate.ToString(UiDefaults.DateOnlyDisplayFormat)</govuk-summary-list-row-value>
                     <govuk-summary-list-row-actions>
-                        <govuk-summary-list-row-action href="@LinkGenerator.Alerts.AddAlert.StartDate(Model.PersonId, Model.JourneyInstance!.InstanceId, fromCheckAnswers: true)" visually-hidden-text="start date">Change</govuk-summary-list-row-action>
+                        <govuk-summary-list-row-action href="@LinkGenerator.Alerts.AddAlert.StartDate(Model.PersonId, Model.JourneyInstance!.InstanceId, returnUrl)" visually-hidden-text="start date">Change</govuk-summary-list-row-action>
                     </govuk-summary-list-row-actions>
                 </govuk-summary-list-row>
             </govuk-summary-list>
@@ -61,7 +63,7 @@
                     <govuk-summary-list-row-key>Reason</govuk-summary-list-row-key>
                     <govuk-summary-list-row-value>@Model.AddReason.GetDisplayName()</govuk-summary-list-row-value>
                     <govuk-summary-list-row-actions>
-                        <govuk-summary-list-row-action href="@LinkGenerator.Alerts.AddAlert.Reason(Model.PersonId, Model.JourneyInstance!.InstanceId, fromCheckAnswers: true)" visually-hidden-text="reason for adding">Change</govuk-summary-list-row-action>
+                        <govuk-summary-list-row-action href="@LinkGenerator.Alerts.AddAlert.Reason(Model.PersonId, Model.JourneyInstance!.InstanceId, returnUrl)" visually-hidden-text="reason for adding">Change</govuk-summary-list-row-action>
                     </govuk-summary-list-row-actions>
                 </govuk-summary-list-row>
                 <govuk-summary-list-row>
@@ -77,7 +79,7 @@
                         }
                     </govuk-summary-list-row-value>
                     <govuk-summary-list-row-actions>
-                        <govuk-summary-list-row-action href="@LinkGenerator.Alerts.AddAlert.Reason(Model.PersonId, Model.JourneyInstance!.InstanceId, fromCheckAnswers: true)" visually-hidden-text="reason details">Change</govuk-summary-list-row-action>
+                        <govuk-summary-list-row-action href="@LinkGenerator.Alerts.AddAlert.Reason(Model.PersonId, Model.JourneyInstance!.InstanceId, returnUrl)" visually-hidden-text="reason details">Change</govuk-summary-list-row-action>
                     </govuk-summary-list-row-actions>
                 </govuk-summary-list-row>
 
@@ -87,7 +89,7 @@
                         <vc:evidence-file-link evidence-file="@Model.EvidenceFile" />
                     </govuk-summary-list-row-value>
                     <govuk-summary-list-row-actions>
-                        <govuk-summary-list-row-action href="@LinkGenerator.Alerts.AddAlert.Reason(Model.PersonId, Model.JourneyInstance!.InstanceId, fromCheckAnswers: true)" visually-hidden-text="evidence">Change</govuk-summary-list-row-action>
+                        <govuk-summary-list-row-action href="@LinkGenerator.Alerts.AddAlert.Reason(Model.PersonId, Model.JourneyInstance!.InstanceId, returnUrl)" visually-hidden-text="evidence">Change</govuk-summary-list-row-action>
                     </govuk-summary-list-row-actions>
                 </govuk-summary-list-row>
             </govuk-summary-list>

diff --git a/...ordSystem/src/TeachingRecordSystem.SupportUi/Pages/Alerts/AddAlert/CheckAnswers.cshtml.cs b/...ordSystem/src/TeachingRecordSystem.SupportUi/Pages/Alerts/AddAlert/CheckAnswers.cshtml.cs
@@ -19,9 +19,6 @@ public class CheckAnswersModel(
     [FromQuery]
     public Guid PersonId { get; set; }
 
-    [FromQuery]
-    public bool FromCheckAnswers { get; set; }
-
     public string? PersonName { get; set; }
 
     public Guid AlertTypeId { get; set; }
@@ -45,16 +42,10 @@ public class CheckAnswersModel(
 
     public override void OnPageHandlerExecuting(PageHandlerExecutingContext context)
     {
-        if (!JourneyInstance!.State.IsComplete)
-        {
-            context.Result = Redirect(linkGenerator.Alerts.AddAlert.Reason(PersonId, JourneyInstance.InstanceId));
-            return;
-        }
-
         var personInfo = context.HttpContext.GetCurrentPersonFeature();
 
         PersonName = personInfo.Name;
-        AlertTypeId = JourneyInstance.State.AlertTypeId!.Value;
+        AlertTypeId = JourneyInstance!.State.AlertTypeId!.Value;
         AlertTypeName = JourneyInstance.State.AlertTypeName;
         Details = JourneyInstance.State.Details;
         Link = JourneyInstance.State.Link;

diff --git a/TeachingRecordSystem/src/TeachingRecordSystem.SupportUi/Pages/Alerts/AddAlert/Details.cshtml b/TeachingRecordSystem/src/TeachingRecordSystem.SupportUi/Pages/Alerts/AddAlert/Details.cshtml
@@ -1,16 +1,16 @@
-@page "/alerts/add/details/{handler?}"
+@page "/alerts/add/details"
 @model TeachingRecordSystem.SupportUi.Pages.Alerts.AddAlert.DetailsModel
 @{
     ViewBag.Title = "Enter details about this alert (optional)";
 }
 
 @section BeforeContent {
-    <govuk-back-link href="@(Model.FromCheckAnswers ? LinkGenerator.Alerts.AddAlert.CheckAnswers(Model.PersonId, Model.JourneyInstance!.InstanceId) : LinkGenerator.Alerts.AddAlert.Type(Model.PersonId, Model.JourneyInstance!.InstanceId))" />
+    <govuk-back-link href="@Model.JourneyInstance!.GetPreviousStepUrl()" />
 }
 
 <div class="govuk-grid-row">
     <div class="govuk-grid-column-two-thirds-from-desktop">
-        <form action="@LinkGenerator.Alerts.AddAlert.Details(Model.PersonId, Model.JourneyInstance!.InstanceId, Model.FromCheckAnswers)" method="post">
+        <form method="post">
             <span class="govuk-caption-l">Add an alert - @Model.PersonName</span>
             <h1 class="govuk-heading-l">@ViewBag.Title</h1>
             <h2 class="govuk-heading-m">@Model.AlertTypeName</h2>

diff --git a/...ngRecordSystem/src/TeachingRecordSystem.SupportUi/Pages/Alerts/AddAlert/Details.cshtml.cs b/...ngRecordSystem/src/TeachingRecordSystem.SupportUi/Pages/Alerts/AddAlert/Details.cshtml.cs
@@ -14,9 +14,6 @@ public class DetailsModel(SupportUiLinkGenerator linkGenerator, EvidenceUploadMa
     [FromQuery]
     public Guid PersonId { get; set; }
 
-    [FromQuery]
-    public bool FromCheckAnswers { get; set; }
-
     public string? PersonName { get; set; }
 
     public string? AlertTypeName { get; set; }
@@ -37,14 +34,11 @@ public async Task<IActionResult> OnPostAsync()
             return this.PageWithErrors();
         }
 
-        await JourneyInstance!.UpdateStateAsync(state =>
-        {
-            state.Details = Details;
-        });
+        var nextStep = linkGenerator.Alerts.AddAlert.Link(PersonId, JourneyInstance!.InstanceId);
 
-        return Redirect(FromCheckAnswers
-            ? linkGenerator.Alerts.AddAlert.CheckAnswers(PersonId, JourneyInstance.InstanceId)
-            : linkGenerator.Alerts.AddAlert.Link(PersonId, JourneyInstance.InstanceId));
+        return await JourneyInstance.UpdateStateAndRedirectToNextStepAsync(
+            state => state.Details = Details,
+            nextStep);
     }
 
     public async Task<IActionResult> OnPostCancelAsync()
@@ -56,15 +50,9 @@ public async Task<IActionResult> OnPostCancelAsync()
 
     public override void OnPageHandlerExecuting(PageHandlerExecutingContext context)
     {
-        if (JourneyInstance!.State.AlertTypeId is null)
-        {
-            context.Result = Redirect(linkGenerator.Alerts.AddAlert.Type(PersonId, JourneyInstance.InstanceId));
-            return;
-        }
-
         var personInfo = context.HttpContext.GetCurrentPersonFeature();
 
         PersonName = personInfo.Name;
-        AlertTypeName = JourneyInstance.State.AlertTypeName;
+        AlertTypeName = JourneyInstance!.State.AlertTypeName;
     }
 }
diff --git a/...hingRecordSystem/src/TeachingRecordSystem.SupportUi/Pages/Alerts/AddAlert/Index.cshtml.cs b/...hingRecordSystem/src/TeachingRecordSystem.SupportUi/Pages/Alerts/AddAlert/Index.cshtml.cs
@@ -11,5 +11,6 @@ public class IndexModel(SupportUiLinkGenerator linkGenerator) : PageModel
     [FromQuery]
     public Guid PersonId { get; set; }
 
-    public IActionResult OnGet() => Redirect(linkGenerator.Alerts.AddAlert.Type(PersonId, JourneyInstance!.InstanceId));
+    public Task<IActionResult> OnGetAsync() =>
+        JourneyInstance!.UpdateStateAndRedirectToNextStepAsync(_ => { }, linkGenerator.Alerts.AddAlert.Type(PersonId, JourneyInstance!.InstanceId));
 }
diff --git a/TeachingRecordSystem/src/TeachingRecordSystem.SupportUi/Pages/Alerts/AddAlert/Link.cshtml b/TeachingRecordSystem/src/TeachingRecordSystem.SupportUi/Pages/Alerts/AddAlert/Link.cshtml
@@ -1,16 +1,16 @@
-@page "/alerts/add/link/{handler?}"
+@page "/alerts/add/link"
 @model TeachingRecordSystem.SupportUi.Pages.Alerts.AddAlert.LinkModel
 @{
     ViewBag.Title = Html.DisplayNameFor(m => m.AddLink);
 }
 
 @section BeforeContent {
-    <govuk-back-link href="@(Model.FromCheckAnswers == true ? LinkGenerator.Alerts.AddAlert.CheckAnswers(Model.PersonId, Model.JourneyInstance!.InstanceId) : LinkGenerator.Alerts.AddAlert.Details(Model.PersonId, Model.JourneyInstance!.InstanceId))" />
+    <govuk-back-link href="@Model.JourneyInstance!.GetBackLinkUrl()" />
 }
 
 <div class="govuk-grid-row">
     <div class="govuk-grid-column-two-thirds-from-desktop">
-        <form action="@LinkGenerator.Alerts.AddAlert.Link(Model.PersonId, Model.JourneyInstance!.InstanceId, Model.FromCheckAnswers)" method="post">
+        <form method="post">
             <span class="govuk-caption-l">Add an alert - @Model.PersonName</span>
 
             <govuk-radios for="AddLink">

diff --git a/TeachingRecordSystem/src/TeachingRecordSystem.SupportUi/Pages/Alerts/AddAlert/Link.cshtml.cs b/TeachingRecordSystem/src/TeachingRecordSystem.SupportUi/Pages/Alerts/AddAlert/Link.cshtml.cs
@@ -14,9 +14,6 @@ public class LinkModel(SupportUiLinkGenerator linkGenerator, EvidenceUploadManag
     [FromQuery]
     public Guid PersonId { get; set; }
 
-    [FromQuery]
-    public bool FromCheckAnswers { get; set; }
-
     public string? PersonName { get; set; }
 
     [BindProperty]
@@ -44,15 +41,15 @@ public async Task<IActionResult> OnPostAsync()
             return this.PageWithErrors();
         }
 
-        await JourneyInstance!.UpdateStateAsync(state =>
-        {
-            state.AddLink = AddLink;
-            state.Link = AddLink == true ? Link : null;
-        });
+        var nextStep = linkGenerator.Alerts.AddAlert.StartDate(PersonId, JourneyInstance!.InstanceId);
 
-        return Redirect(FromCheckAnswers
-            ? linkGenerator.Alerts.AddAlert.CheckAnswers(PersonId, JourneyInstance.InstanceId)
-            : linkGenerator.Alerts.AddAlert.StartDate(PersonId, JourneyInstance.InstanceId));
+        return await JourneyInstance.UpdateStateAndRedirectToNextStepAsync(
+            state =>
+            {
+                state.AddLink = AddLink;
+                state.Link = AddLink == true ? Link : null;
+            },
+            nextStep);
     }
 
     public async Task<IActionResult> OnPostCancelAsync()