Add a diagram showing what the request flow looks like

README.md

@@ -16,7 +16,7 @@ These APIs are freely available, and allow anybody to use our data.
 
 -	The **search API** is for running ad hoc searches, and it powers the collections search at [wellcomecollection.org/collections][search].
 	We have [documentation][search_docs] for external developers who want to use this API.
-	
+
 	To help us develop the search API, we have a tool called **rank**.
 	This helps us measure the quality of our search ranking, by checking that certain queries return known-relevant results.
 
@@ -36,6 +36,8 @@ These APIs are used on the Wellcome Collection website, but they require authent
 	The **requests API** allows them to manage their requests on the Wellcome Collection website: either placing requests, or checking the status of their outstanding requests.
 	It forward requests to our library management systems, so that library staff know which items to retrieve from the stores.
 
+See [notes on the requesting flow](docs/requesting_flow.md) for more information.
+
 [search]: https://wellcomecollection.org/collections
 [search_docs]: https://developers.wellcomecollection.org/catalogue
 [pipeline]: https://github.com/wellcomecollection/catalogue-pipeline

docs/requesting_flow.md

@@ -0,0 +1,36 @@
+# How users request items
+
+Users can use the website to request items to view in the library; we provide a series of APIs to help them do that.
+
+This is what the flow looks like:
+
+```mermaid
+sequenceDiagram
+     participant user
+     participant front end
+     participant works API
+     participant items API
+     participant requests API
+     participant Sierra
+
+     user->>front end: views a works page<br/> with items
+
+     front end->>works API: get information about<br/>items on a work
+     works API->>front end:
+
+     front end->>items API: get up-to-date status of items<br/>using catalogue ID
+     items API->>works API: get matching Sierra IDs<br/>for catalogue IDs
+     works API->>items API:
+     items API->>Sierra: get latest Sierra item data
+     Sierra->>items API:
+     items API->>front end: returns items with up-to-date status
+     front end->>front end: render items with<br/>updated information
+
+     user->>front end: clicks "Request item"
+     front end->>requests API: request an item using catalogue ID
+     requests API->>works API: get matching Sierra IDs<br/>for catalogue IDs
+     works API->>requests API:
+     requests API->>Sierra: place request in<br/>Sierra
+     Sierra->>requests API:
+     requests API->>front end: return result of request to user
+```