Merge pull request #80 from dxw/docs/subscriber-api-sequence-diagrams

Document plan for Subscriber API

.prettierignore

@@ -25,6 +25,7 @@
 *.txt
 *.gz
 *.map
+*.mermaid
 /public/assets/*
 leaflet.js
 leaflet.css

doc/subscriber-api.md

@@ -0,0 +1,60 @@
+# Subscriber API
+
+The airTEXT service will not handle subscriptions for air quality alerts
+directly: they will be passed through to CERC, who will record these user
+subscriptions and send out the alerts via email, text or phone.
+
+We have mapped out two key user journeys using sequence diagrams to show the
+flow of data between participants:
+
+- the user signing up for alerts or signing in to view existing subscriptions
+- this airTEXT service under development
+- CERC's Subscriber API currently being agreed
+- a notification service for authentication flows, e.g. [GOV.UK Notify][]
+
+## Sequence diagrams
+
+### User signs in to view existing alert subscriptions
+
+- So that I can edit my existing alert subscriptions
+- As a user with existing subscriptions
+- I want to supply either an email or phone number to authenticate and see a
+  list of associated alert subscriptions
+
+#### Artefacts
+
+- [User signs in to view existing subscriptions (Mermaid)][]
+- [User signs in to view existing subscriptions (PNG)][]
+
+### New user signs up for alert subscriptions
+
+- So that I can receive alerts for the locations which are important to me and
+  have them delivered in a way which suits me
+- As a new airTEXT user
+- I want to specify i) which zones I want alerts for and ii) how I want those
+  alerts delivered and have these alert subscriptions associated with a verified
+  email and/or phone number
+
+#### Artefacts
+
+- [New user signs up for alert subscriptions (Mermaid)][]
+- [New user signs up for alert subscriptions (PNG)][]
+
+## CERC subscriber API
+
+We've suggested an API which would provide a interface for airTEXT to exchange
+subscriber/subscription information with CERC:
+
+- [Proposed Subscriber API between airTEXT and CERC][]
+
+[GOV.UK Notify]: https://www.notifications.service.gov.uk
+[User signs in to view existing subscriptions (Mermaid)]:
+  ./subscriber_api/sequence_user_views_existing_subscriptions.mermaid
+[User signs in to view existing subscriptions (PNG)]:
+  ./subscriber_api/sequence_user_views_existing_subscriptions.png
+[New user signs up for alert subscriptions (Mermaid)]:
+  ./subscriber_api/sequence_new_user_signs_up_to_alerts.mermaid
+[New user signs up for alert subscriptions (PNG)]:
+  ./subscriber_api/sequence_new_user_signs_up_to_alerts.png
+[Proposed Subscriber API between airTEXT and CERC]:
+  ./subscriber_api/proposed_subscriber_api.md

doc/subscriber_api/proposed_subscriber_api.md

@@ -0,0 +1,57 @@
+# Proposed Subscriber API
+
+**Oct 24, 2024**
+
+## Operations on subscribers
+
+### Find a user's SubscriberID
+
+GET to `/find-subscriber` with
+
+- `email` or
+- `phone`
+
+returns subscriber representation, status 200:
+
+- subscriberId (UUID)
+
+returns 404 if not found
+
+## Operations on subscriptions
+
+### List subscriptions for subscriber
+
+We'll need this to:
+
+- show a logged in user their list of subscriptions
+- delete all subscriptions if a user want to withdraw from the service fully
+
+GET `/subscriptions/{subscriberId}`
+
+returns list of subscriptions:
+
+- subscriptionId
+- subscriberId
+- zone or zoneID
+- medium (email | voice | sms)
+
+### Create subscription
+
+POST to `/subscriptions` with:
+
+- subscriberId (optional)
+- zone
+- medium (email | txt | voice)
+
+returns subscription ID (UUID), status 201
+
+If a UUID is not supplied a new `subscriberID` UUID is generated (and can then
+by used for making further subscriptions for the a new user)
+
+### Delete subscription
+
+DELETE to` /subscriptions` with:
+
+- subscriptionId UUID
+
+returns `subscriptionId`, status 200

doc/subscriber_api/sequence_new_user_signs_up_to_alerts.mermaid

@@ -0,0 +1,50 @@
+sequenceDiagram
+
+title New user subscribes to alerts
+
+# Offer user a list of zones and delivery mechanisms
+
+note over user: Offer user a list of zones and delivery mechanisms
+
+
+airtext ->> user: subscribe to alerts?<br/>(specifiying delivery mechanisms)
+user ->> airtext: subscribe to various alerts
+
+
+alt if email delivery requested
+
+	airtext ->> auth_notifier: send_email<br/>(with auth code)
+	auth_notifier ->> user: sends email<br/>with auth code
+	user ->> airtext: user enters auth code
+
+	alt if email verified (auth code entered correctly)
+		loop for each email subscription requested
+
+			note over airtext, cerc_api: POST /subscriptions takes optional UUID.<br/>Our first POST has no UUID.<br/>The returned UUID is used for subsequent POSTs.
+
+			airtext ->> cerc_api: POST /subscriptions
+			cerc_api ->> airtext: returns 201 with UUID
+		end
+	end
+
+else if SMS / voice delivery requested
+
+	airtext ->> auth_notifier: send_sms<br/>(with auth code)
+	auth_notifier ->> user: sends SMS<br/>with auth code
+	user ->> airtext: user enters auth code
+
+	alt if SMS verified (auth code entered correctly)
+		loop for each SMS / Voice subscription requested
+			airtext ->> cerc_api: POST /subscriptions
+			cerc_api ->> airtext: returns 201 with UUID
+		end
+	end
+
+end
+
+# Display list of subscriptions and any error
+# messages where phone or email was not verified
+
+airtext ->> cerc_api: GET /subscriptions for UUID
+cerc_api ->> airtext: returns list of subscriptions
+airtext ->> user: show list of subscriptions<br/>(and/or error if email/sms unverified)

doc/subscriber_api/sequence_user_views_existing_subscriptions.mermaid

@@ -0,0 +1,35 @@
+sequenceDiagram
+
+title Existing user logs in to view subscriptions
+
+
+
+
+user ->> airtext: starts login<br/>(supplying email or phone)
+airtext ->> cerc_api: GET /find-subscriber
+
+
+alt if user unknown
+	cerc_api ->> airtext: returns 404
+	airtext ->> user: try again or create new account
+
+else else if email or phone number is found at CERC
+	cerc_api ->> airtext: returns UUID
+	airtext ->> auth_notifier: send_email or send_sms<br/>(with auth code)
+	auth_notifier ->> user: sends email or sms<br/>ith auth code
+
+	activate airtext
+
+	user ->> airtext: completes login by<br/>entering auth code
+
+	note right of airtext: start user session
+
+	airtext ->> user: redirect to user dashboard
+end
+
+user ->> airtext: view subscriptions
+airtext ->> cerc_api: GET /subscriptions/{subscriberId}
+cerc_api ->> airtext: returns list of subscriptions
+airtext ->> user: show list of subscriptions
+
+deactivate airtext