Skip to content

Update the submission email sequence diagram #244

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
stephencdaly merged 2 commits into from
Feb 9, 2026
Merged

Update the submission email sequence diagram #244

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
64201e3
Update the submission email sequence diagram
stephencdaly Feb 6, 2026
40f9c03
Update forms-runner class diagram
stephencdaly Feb 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 18 additions & 10 deletions diagrams/class-diagrams/runner.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`
```
12 changes: 6 additions & 6 deletions diagrams/sequence-diagrams/sending-submission-emails.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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<br/> message_id from SES as the delivery_reference

ses-)inbox: send email
note over ses,inbox: happens some time later
Expand Down Expand Up @@ -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<br/> 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<br/> message_id from the SQS message
worker->>worker: Log with the submission details
end

Expand Down Expand Up @@ -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<br/> 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
```