Skip to content

Commit 24de7c8

Browse files
jableyjabley
committed
Add architecture documentation
This is possibly a moving target but I wanted to get capture my understanding whilst preparing to take this to the Technical Review Group - https://architecture.digital.nhs.uk/trg
1 parent 7136f3b commit 24de7c8

2 files changed

Lines changed: 196 additions & 24 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -126,30 +126,7 @@ The gateway is designed to run as a set of Windows Services on-premises.
126126

127127
## Architecture
128128

129-
This gateway implements a lightweight DICOM service architecture:
130-
131-
1. **DICOM Worklist Server** - Provides scheduled procedure information to modalities
132-
2. **DICOM PACS Server** - Receives and stores medical images ([docs](docs/pacs/README.md))
133-
3. **Event Processing** - Processes MPPS status updates and image metadata
134-
4. **Azure Relay Communication** - Bidirectional communication with cloud service
135-
136-
### PACS Server
137-
138-
The PACS server provides C-STORE functionality for receiving medical images:
139-
- Hash-based storage for scalability
140-
- SQLite metadata indexing
141-
- Thread-safe concurrent access
142-
- Docker containerized deployment
143-
144-
See [PACS documentation](docs/pacs/README.md) for detailed information.
145-
146-
### Relay Listener
147-
148-
The Relay Listener handles incoming messages from the cloud service via Azure Relay:
149-
- Listens on configured Hybrid Connection
150-
- Processes worklist actions (e.g., create worklist item)
151-
152-
See [Relay Listener documentation](docs/relay-listener/README.md) for details.
129+
See [docs/architecture.md](docs/architecture.md)
153130

154131
## Testing
155132

‎docs/architecture.md‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
# Gateway Architecture and Data Flows
2+
3+
This document summarises the architecture of the Manage Breast Screening Gateway, its protocols and data flows.
4+
5+
## Overview
6+
7+
This gateway implements a lightweight DICOM service architecture:
8+
9+
1. **DICOM Worklist Server** - Provides scheduled procedure information to modalities ([docs](mwl/README.md))
10+
2. **DICOM PACS Server** - Receives and stores medical images ([docs](pacs/README.md))
11+
3. **Event Processing** - Processes appointment status updates and image metadata ([docs](upload/README.md))
12+
4. **Azure Relay Communication** - Bidirectional communication with cloud service ([docs](relay-listener/README.md))
13+
14+
### Modality Worklist (MWL) Server
15+
16+
The MWL server provides `C-FIND` functionality for modalities to query the scheduled procedure information.
17+
18+
See [MWL documentation](mwl/README.md) for detailed information.
19+
20+
### PACS Server
21+
22+
The PACS server provides `C-STORE` functionality for receiving medical images:
23+
24+
- Content-addressable storage
25+
- SQLite metadata indexing
26+
- Thread-safe concurrent access
27+
- Docker containerized deployment
28+
29+
See [PACS documentation](pacs/README.md) for detailed information.
30+
31+
### Relay Listener
32+
33+
The Relay Listener handles incoming messages from the cloud service via Azure Relay:
34+
35+
- Listens on configured Hybrid Connection
36+
- Processes worklist actions (e.g., create worklist item)
37+
38+
See [Relay Listener documentation](relay-listener/README.md) for details.
39+
40+
The gateway bridges on-premises breast screening modalities with the cloud-based Manage Breast Screening platform.
41+
42+
Core runtime services:
43+
44+
- PACS Server (`C-STORE` receiver)
45+
- Modality Worklist (MWL) Server (`C-FIND` responder)
46+
- Relay Listener (Azure Relay WebSocket listener over outbound HTTPS)
47+
- Upload Service (background poller and HTTP uploader)
48+
49+
## Topology
50+
51+
```mermaid
52+
graph TB
53+
subgraph "On-Premises"
54+
subgraph "Trust IT"
55+
MOD["Modality\nMammography System"]
56+
end
57+
58+
subgraph "Gateway"
59+
PACS["PACS Server\nPort 4244\nDICOM C-STORE SCP\nListening"]
60+
MWL["MWL Server\nPort 4243\nDICOM C-FIND SCP\nListening"]
61+
RELAY["Relay Listener\nAzure Relay\nListening over outbound HTTPS"]
62+
UPLOAD["Upload Service\nPolling loop"]
63+
64+
PACSDB[("PACS SQLite DB\n+ DICOM file storage")]
65+
MWLDB[("MWL SQLite DB")]
66+
end
67+
end
68+
69+
subgraph "Cloud"
70+
MANAGE["Manage Breast Screening API"]
71+
AR["Azure Relay"]
72+
end
73+
74+
MOD -->|"C-STORE Images"| PACS
75+
MOD -->|"C-FIND Worklist Query"| MWL
76+
77+
PACS --> PACSDB
78+
MWL --> MWLDB
79+
80+
AR -->|"Worklist actions"| RELAY
81+
RELAY --> MWLDB
82+
83+
UPLOAD -->|"Poll pending uploads"| PACSDB
84+
UPLOAD -->|"Lookup source_message_id"| MWLDB
85+
UPLOAD -->|"HTTP multipart upload"| MANAGE
86+
```
87+
88+
## Protocols, Inputs, Outputs, and Transfer Direction
89+
90+
| Service | Input | Output | Protocol(s) | Listening or Initiating? |
91+
| --- | --- | --- | --- | --- |
92+
| PACS Server | DICOM image objects from modality | Compressed/stored DICOM + PACS metadata rows | DICOM `C-STORE` (+ `C-ECHO`) | **Listening** on default port `4244` |
93+
| MWL Server | Worklist queries from modality | Matching worklist records | DICOM `C-FIND` (+ MPPS updates) | **Listening** on default port `4243` |
94+
| Relay Listener | GatewayAction-style worklist messages from cloud service | Created/updated MWL worklist items | Azure Relay WebSocket over outbound HTTPS (`443`) | **Listening** via persistent outbound connection |
95+
| Upload Service | Pending PACS rows + DICOM files + MWL linkage data | Uploaded image payloads and status updates | HTTPS `POST` multipart/form-data | **Initiating** outbound HTTP requests |
96+
97+
## End-to-End Data Flows
98+
99+
### 1. Worklist down to modality
100+
101+
This happens via 2 flows:
102+
103+
1. Manage service emits worklist action via [Azure Relay websocket](https://learn.microsoft.com/en-us/azure/azure-relay/relay-hybrid-connections-protocol).
104+
2. Gateway relay listener receives message and writes MWL item to MWL SQLite DB.
105+
3. Separately, the Modality sends DICOM `C-FIND` query to MWL server.
106+
4. MWL server responds with matching scheduled procedure items.
107+
108+
```mermaid
109+
graph TB
110+
subgraph "Cloud"
111+
MANAGE["Manage Breast Screening API"]
112+
AR["Azure Relay"]
113+
end
114+
115+
subgraph "On Premises"
116+
subgraph "Trust IT"
117+
MOD["Modality\nMammography System"]
118+
end
119+
120+
subgraph "Gateway"
121+
MWL["MWL Server\nPort 4243\nDICOM C-FIND SCP\nListening"]
122+
RELAY["Relay Listener\nAzure Relay\nListening over outbound HTTPS"]
123+
124+
MWLDB[("MWL SQLite DB")]
125+
end
126+
end
127+
128+
MANAGE -->|"1. Emit worklist actions"| AR
129+
AR -->|"Emit worklist actions"| RELAY
130+
RELAY -->|"2. Store MWL item"| MWLDB
131+
132+
MOD -->|"3. C-FIND"| MWL
133+
MWL -->|"4. Retrieve worklist items"| MWLDB
134+
```
135+
136+
### 2. Images up to cloud
137+
138+
This also happens via 2 flows:
139+
140+
1. Modality sends DICOM `C-STORE` to PACS server.
141+
2. PACS validates tags and pixel data, decompresses if required, resizes, and recompresses (JPEG 2000 lossy).
142+
3. PACS stores file in content-addressable filesystem layout and records metadata in PACS SQLite DB.
143+
4. In parallel, the Upload service polls for `PENDING` items, reads the DICOM file, and finds `source_message_id` via MWL data.
144+
5. Upload service sends multipart HTTPS upload to Manage API with `X-Source-Message-ID`.
145+
6. Upload status is updated (`COMPLETE` or retried/fails after max retries).
146+
147+
```mermaid
148+
graph TB
149+
subgraph "Cloud"
150+
MANAGE["Manage Breast Screening API"]
151+
AR["Azure Relay"]
152+
end
153+
154+
subgraph "On Premises"
155+
subgraph "Trust IT"
156+
MOD["Modality\nMammography System"]
157+
end
158+
159+
subgraph "Gateway"
160+
PACS["PACS Server\nPort 4244\nDICOM C-STORE SCP\nListening"]
161+
UPLOAD["Upload Service\nPolling loop"]
162+
163+
PACSDB[("PACS SQLite DB\n+ DICOM file storage")]
164+
MWLDB[("MWL SQLite DB")]
165+
end
166+
end
167+
168+
MOD -->|"1. C-STORE"| PACS
169+
PACS -->|"2. Validate"| PACS
170+
PACS -->|"3. Store"| PACSDB
171+
172+
UPLOAD -->|"4. Poll"| MWLDB
173+
UPLOAD -->|"4. Read DICOM file"| PACSDB
174+
UPLOAD -->|"5. upload"| MANAGE
175+
UPLOAD --> |"6. Update status"| MWLDB
176+
```
177+
178+
### 3. Worklist status progression
179+
180+
- `SCHEDULED` when created from relay message.
181+
- Moves to `IN PROGRESS` when image activity begins (`C-STORE` observed).
182+
- Finalised by MPPS events (`COMPLETED` or `DISCONTINUED`).
183+
- Daily backup-and-clear is run by scheduled task (`reset_main.py`), preparing next day’s workload.
184+
185+
## Storage and Processing Notes
186+
187+
- PACS file storage uses content-addressable paths derived from `SOPInstanceUID`.
188+
- PACS metadata and MWL data are stored in separate SQLite databases.
189+
- Compression and resizing are intentional to support thumbnail/display workflows in the cloud UI; full-resolution clinical images remain in BSU internal PACS.
190+
191+
## Deployment Characteristics
192+
193+
- PACS and MWL are designed to run as separate services/containers.
194+
- Gateway can operate behind strict firewalls because relay communication is maintained via outbound HTTPS.
195+
- Upload is asynchronous and retry-based (polling + exponential backoff).

0 commit comments

Comments
 (0)