CCM-14319 mesh validation architecture (#201)

* CCM-14319: Added MeshInvoxMessageInvalid event
* CCM-14319: Updated diagrams for MESHInboxMessageInvalid
* CCM-14319: Update readme
* CCM-14319: Added SSM to MESHAcknowledger diagram

Author: tdroza-nhs

README.md

@@ -4,19 +4,24 @@ title: c4code-mesh-acknowledger
 
 ---
 
-## MESH Acknowledge
-
 ```mermaid
 architecture-beta
     group meshAcknowledger(cloud)[MeshAcknowledger]
     service meshDownloaded(aws:res-amazon-eventbridge-event)[MESHInboxMessageDownloaded Event]
+    service meshInvalid(aws:res-amazon-eventbridge-event)[MESHInboxMessageInvalid Event]
     service meshAcknowledged(aws:res-amazon-eventbridge-event)[ MESHInboxMessageAcknowledged Event]
     service meshAckQueue(logos:aws-sqs)[MeshAcknowledgement Queue] in meshAcknowledger
+    service clientConfig(aws:res-aws-systems-manager-parameter-store)[Client Configuration] in meshAcknowledger
     service meshAckLambda(logos:aws-lambda)[MeshAcknowledger] in meshAcknowledger
     service mesh(server)[MESH]
 
-    meshDownloaded:R --> L:meshAckQueue
+    junction j1
+
+    meshDownloaded:R -- T:j1
+    meshInvalid:R -- L:j1
+    j1:R --> L:meshAckQueue
     meshAckQueue:R --> L:meshAckLambda
+    clientConfig:B --> T:meshAckLambda
     meshAckLambda:B --> T:mesh
     meshAckLambda:R --> L:meshAcknowledged
 ```

docs/collections/_diagrams/c4code-mesh-acknowledger.md

@@ -8,13 +8,19 @@ title: c4code-mesh-poller
 architecture-beta
     group meshPoller(cloud)[MeshPoller]
     service meshDownloaded(aws:res-amazon-eventbridge-event)[MeshPollerTimerExpired Event]
-    service pdmSaved(aws:res-amazon-eventbridge-event)[MESHInboxMessageReceived Event]
+    service meshReceived(aws:res-amazon-eventbridge-event)[MESHInboxMessageReceived Event]
+    service meshInvalid(aws:res-amazon-eventbridge-event)[MESHInboxMessageInvalid Event]
     service meshPollLambda(logos:aws-lambda)[MeshPoll] in meshPoller
     service clientConfig(aws:res-aws-systems-manager-parameter-store)[Client Configuration] in meshPoller
     service mesh(server)[MESH]
 
+    junction j1
+
     meshDownloaded:R --> L:meshPollLambda
     clientConfig:B --> T:meshPollLambda
     meshPollLambda:B --> T:mesh
-    meshPollLambda:R --> L:pdmSaved
+    meshPollLambda:R -- L:j1
+    j1:T --> L:meshReceived
+    j1:R --> L:meshInvalid
+
 ```

docs/collections/_diagrams/c4code-mesh-poller.md

@@ -0,0 +1,10 @@
+---
+title: mesh-inbox-message-invalid
+type: uk.nhs.notify.digital.letters.mesh.inbox.message.invalid.v1
+nice_name: MESHInboxMessageInvalid
+service: MESH Services
+schema_envelope:  https://notify.nhs.uk/cloudevents/schemas/digital-letters/2025-10-draft/events/uk.nhs.notify.digital.letters.mesh.inbox.message.invalid.v1.schema.json
+schema_data: https://notify.nhs.uk/cloudevents/schemas/digital-letters/2025-10-draft/data/digital-letters-mesh-inbox-message-invalid-data.schema.json
+---
+
+This event is published when the MESHPoller detects a new message in the MESH mailbox that is deemed invalid and should not be downloaded.

docs/collections/_events/mesh-inbox-message-invalid.md

@@ -0,0 +1,16 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+title: MESHInboxMessageReceived Data
+description: Data payload of the MESHInboxMessageReceived event
+type: object
+additionalProperties: false
+properties:
+  meshMessageId:
+    $ref: ../defs/mesh.schema.yaml#/properties/meshMessageId
+  senderId:
+    $ref: ../defs/requests.schema.yaml#/properties/senderId
+  failureCode:
+    $ref: ../defs/requests.schema.yaml#/properties/failureCode
+required:
+  - meshMessageId
+  - senderId
+  - failureCode

src/cloudevents/domains/digital-letters/2025-10-draft/data/digital-letters-mesh-inbox-message-invalid-data.schema.yaml

@@ -31,4 +31,9 @@ properties:
     type: string
     description: The ODS Code of the sending organisation. Used to identify the sender in NHS App
     examples:
-      - ""
+      - "X26"
+  failureCode:
+    type: string
+    description: The failure code indicating the reason for the message being invalid
+    examples:
+      - "LOCALID_HEADER_MISSING"

src/cloudevents/domains/digital-letters/2025-10-draft/defs/requests.schema.yaml

@@ -0,0 +1,23 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+title: MESHInboxMessageInvalid
+type: object
+allOf:
+  - $ref: ../digital-letters-mesh-profile.schema.yaml
+properties:
+  type:
+    type: string
+    const: uk.nhs.notify.digital.letters.mesh.inbox.message.invalid.v1
+    description: Concrete versioned event type string for this event (.vN suffix).
+  source:
+    type: string
+    pattern: ^/nhs/england/notify/(production|staging|development|uat)/(primary|secondary|dev-[0-9]+)/data-plane/digitalletters/mesh
+    description: Event source for digital letters.
+
+  dataschema:
+    type: string
+    const: ../data/digital-letters-mesh-inbox-message-invalid-data.schema.yaml
+    description: Canonical URI of the event's data schema.
+    examples:
+      - digital-letters-mesh-inbox-message-invalid-data.schema.yaml
+  data:
+    $ref: ../data/digital-letters-mesh-inbox-message-invalid-data.schema.yaml