added architecture overview diagram and simplified PR template (#1447)

Co-authored-by: Thomas-Boyle <45789537+Thomas-Boyle@users.noreply.github.com>

Author: avshetty1980

.github/pull_request_template.md

@@ -1,25 +1,7 @@
-## Summary
+## PR Description
 
-- Routine Change
-- :exclamation: Breaking Change
-- :robot: Operational or Infrastructure Change
-- :sparkles: New Feature
-- :warning: Potential issues that might be caused by this change
+Description of the changes made.
 
-Add any other relevant notes or explanations here. **Remove this line if you have nothing to add.**
+## How were the changes tested
 
-## Reviews Required
-
-- [x] Dev
-- [ ] Test
-- [ ] Tech Author
-- [ ] Product Owner
-
-## Review Checklist
-
-:information_source: This section is to be filled in by the **reviewer**.
-
-- [ ] I have reviewed the changes in this PR and they fill all of the acceptance criteria of the ticket.
-- [ ] If there were infrastructure, operational, or build changes, I have made sure there is sufficient evidence that the changes will work.
-- [ ] If there were changes that are outside of the regular release processes e.g. account infrastructure to setup, manual setup for external API integrations, secrets to set, then I have checked that the developer has flagged this to the Tech Lead as release steps.
-- [ ] I have checked that no Personal Identifiable Data (PID) is logged as part of the changes.
+Describe how the changes were tested

docs/architecture/system-overview.md

@@ -0,0 +1,76 @@
+# System Overview
+
+This page gives a high-level view of the Immunisation FHIR API runtime architecture.
+
+It focuses on the API path, batch ingestion path, outbound notification flow, runtime configuration, and NHS number change handling.
+
+## High-Level Diagram
+
+```mermaid
+flowchart LR
+    subgraph Ingress[Ingress and API]
+        Suppliers[Supplier systems] --> Apigee[Apigee proxy\nOAuth, rate limiting, supplier header]
+        Apigee --> ApiGw[AWS API Gateway HTTP API]
+        ApiGw --> Backend[Backend API Lambdas\nCRUD, search, status]
+        Backend --> IEDS[(IEDS DynamoDB\nImmunisation event store)]
+    end
+
+    subgraph Batch[Batch ingestion]
+        SupplierFiles[Supplier batch files in S3] --> Filename[Filename Processor Lambda]
+        Mesh[MESH mailbox bucket] --> MeshProc[Mesh Processor Lambda]
+        MeshProc --> Filename
+        Filename --> BatchCreated[SQS FIFO\nbatch-file-created]
+        BatchCreated --> BatchFilter[Batch Processor Filter Lambda]
+        BatchFilter --> SupplierQueue[SQS FIFO\nsupplier metadata queue]
+        SupplierQueue --> BatchPipe[EventBridge Pipe]
+        BatchPipe --> RecordProcessor[ECS Fargate Record Processor]
+        RecordProcessor --> Kinesis[Kinesis data stream]
+        Kinesis --> Forwarder[Record Forwarder Lambda]
+        Forwarder --> IEDS
+        Forwarder --> AckQueue[SQS FIFO\nack metadata queue]
+        AckQueue --> Ack[Ack Backend Lambda]
+    end
+
+    subgraph Outbound[Outbound notifications]
+        IEDS -->|DynamoDB stream| Delta[Delta Lambda]
+        Delta --> DeltaTable[(Delta DynamoDB)]
+        DeltaTable -->|DynamoDB stream| MnsPipe[EventBridge Pipe]
+        MnsPipe --> MnsQueue[SQS\nmns-outbound-events]
+        MnsQueue --> MnsPublisher[MNS Publisher Lambda]
+        MnsPublisher --> Subscribers[MNS subscribers]
+    end
+
+    subgraph Config[Runtime config]
+        ConfigBucket[S3 config bucket] --> RedisSync[Redis Sync Lambda]
+        RedisSync --> Redis[(Redis cache\npermissions, disease mappings, config)]
+        Redis --> Backend
+        Redis --> Filename
+        Redis --> RecordProcessor
+        Redis --> Forwarder
+    end
+
+    subgraph IdSync[Identity sync]
+        MnsIdEvent[MNS NHS number change event] --> IdQueue[SQS\nid-sync-queue]
+        IdQueue --> IdSyncLambda[ID Sync Lambda]
+        IdSyncLambda --> IEDS
+    end
+```
+
+## Key Runtime Stores
+
+| Store          | Purpose                                                             |
+| -------------- | ------------------------------------------------------------------- |
+| IEDS DynamoDB  | System of record for immunisation events                            |
+| Delta DynamoDB | Outbound change store derived from IEDS stream events               |
+| Redis          | Runtime cache for permissions, disease mappings, and related config |
+| Audit table    | Batch-processing control state, deduplication, and status tracking  |
+
+## Design Notes
+
+- The filename processor is the batch entry point for files placed in the source bucket.
+- The audit table is for deduplication, processing state, and ordering decisions.
+- The batch processor filter ensures only one event is processed at a time for a given supplier and vaccine-type combination.
+- The supplier metadata FIFO queue preserves ordering before work is dispatched to ECS through EventBridge Pipe.
+- ECS is used for record processing because batch row processing can be long-running.
+- The record forwarder is the component that applies processed batch changes to IEDS.
+- ACK creation is part of the batch lifecycle.