From 64201e37d73d2c885fc4f0a1816157282ed717ef Mon Sep 17 00:00:00 2001 From: Stephen Daly Date: Fri, 6 Feb 2026 17:48:13 +0000 Subject: [PATCH 1/2] Update the submission email sequence diagram We've migrated the forms-runner database to store details about the status of the email delivery for a submission into a separate `deliveries` table. Update the sequence diagram to reflect this change. --- .../sequence-diagrams/sending-submission-emails.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/diagrams/sequence-diagrams/sending-submission-emails.md b/diagrams/sequence-diagrams/sending-submission-emails.md index 2af74485d..95d9684f3 100644 --- a/diagrams/sequence-diagrams/sending-submission-emails.md +++ b/diagrams/sequence-diagrams/sending-submission-emails.md @@ -75,8 +75,7 @@ break error end ses->>worker: return message_id -worker->>runner-db: set mail_message_id on Submission -worker->>runner-db: set the last_delivery_attempt timestamp on Submission +worker->>runner-db: create a Delivery record with the
message_id from SES as the delivery_reference ses-)inbox: send email note over ses,inbox: happens some time later @@ -116,15 +115,15 @@ worker->>solidqueue-db: enqueue recurring receive bounces job worker->>solidqueue-db: dequeue receive bounces job worker->>sqs: get messages from bounces and complaints queue alt there is a bounce SQS message - worker->>runner-db: get Submission by the message_id in the SQS message - worker->>runner-db: update delivery_status of Submission to "bounced" + worker->>runner-db: get Delivery where the delivery_reference is the
message_id from the SQS message + worker->>runner-db: set the failed_at timestamp on the Delivery worker->>worker: Log with the submission details worker->>sentry: send error event sentry->>support: Alert via Slack support->>support: Identify why the email bounced support->>support: Run rake task to retry submission else there is a complaint SQS message - worker->>runner-db: get Submission by the message_id in the SQS message + worker->>runner-db: get Delivery where the delivery_reference is the
message_id from the SQS message worker->>worker: Log with the submission details end @@ -152,7 +151,8 @@ actor support as Forms team tech support worker->>solidqueue-db: enqueue recurring receive deliveries job worker->>solidqueue-db: dequeue receive deliveries job worker->>sqs: get messages from deliveries queue -worker->>runner-db: get Submission by the message_id in the SQS message +worker->>runner-db: get Delivery where the delivery_reference is the
message_id from the SQS message +worker->>runner-db: set the delivered_at timestamp on the Delivery worker->>worker: log a "form_submission_delivered" event note over worker,runner-db: we don't currently use the "delivered" status for anything other than for information ``` From 40f9c0357c1c6b1e262ce30a5270918fcf5cd253 Mon Sep 17 00:00:00 2001 From: Stephen Daly Date: Mon, 9 Feb 2026 10:35:03 +0000 Subject: [PATCH 2/2] Update forms-runner class diagram --- diagrams/class-diagrams/runner.md | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/diagrams/class-diagrams/runner.md b/diagrams/class-diagrams/runner.md index 97d21e042..99e4f5d3f 100644 --- a/diagrams/class-diagrams/runner.md +++ b/diagrams/class-diagrams/runner.md @@ -7,14 +7,22 @@ title: GOV.UK Forms Runner app class diagram ```mermaid classDiagram - direction RL - class `Submission` - `Submission` : +jsonb answers - `Submission` : +jsonb form_document - `Submission` : +integer form_id - `Submission` : +string mail_message_id - `Submission` : +string mail_status - `Submission` : +string mode - `Submission` : +string reference - `Submission` : +datetime sent_at + direction RL + class `Delivery` + `Delivery` : +datetime delivered_at + `Delivery` : +string delivery_reference + `Delivery` : +datetime failed_at + `Delivery` : +string failure_reason + `Delivery` : +datetime last_attempt_at + class `Submission` + `Submission` : +jsonb answers + `Submission` : +jsonb form_document + `Submission` : +integer form_id + `Submission` : +string mode + `Submission` : +string reference + `Submission` : +string submission_locale + class `SubmissionDelivery` + `Submission` --> `SubmissionDelivery` + `Delivery` --> `SubmissionDelivery` + `Submission` "0..*" -- "0..*" `Delivery` ```