Merge pull request #1759 from kiminkim724/notifications-readme

Update README for Notifications

Author: Mephistic

functions/src/notifications/README.md

@@ -6,45 +6,59 @@ The notification feature is responsible for sending notifications to users based
 
 ## Features
 
-- **Topic-Based Notifications**: Users receive notifications based on topics they are interested in.
-- **Scheduled Triggers**: Functions are triggered based on a publication schedule.
-- **Multi-Environment Support**: Both HTTP callable and pubSub versions of functions are available for testing and production, respectively.
+- **Topic-Based Notifications**: Users receive notifications based on topics they are subscribed to.
+  - Each user has a list of topics created when subscribing to a Bill, User, or Organization.
+  - Topics can be categorized as either Bill Topics or Organization Topics:
+    - `bill-[courtId]-[billId]`: Triggers when a subscribed Bill has a history update or when testimony is posted on the Bill.
+    - `testimony-[userId]`: Triggers when a subscribed User or Organization posts testimony.
+- **Notification Events**
+  - A BillHistoryNotificationEvent is created when a subscribed Bill has an updated history
+  - A TestimonySubmissionNotificationEvent is created when a subscribed Bill has testimony published and when a Organization/User publishes testimony
+- **Event Triggers**: Functions are triggered based on changes in the `notificationEvents` collection
 
 ## Architecture
 
-### Events
+### Notification Events
 
 A user could be subscribed to a given topic, and receive a notification of a bill or profile (such as an organization) that fall under that topic have an event.
 
-Example event regarding a bill:
-![example-bill-event](/functions/src/notifications/images/example-bill-event.png)
+Example event regarding a bill history update:
+![example-bill-notification-event](/functions/src/notifications/images/example-bill-notification-event.png)
 
-Example event regarding an organization:
-![example-org-event](/functions/src/notifications/images/example-bill-event.png)
-
-Example event created from the web scraper (notice the difference in fields):
-![example-scraped_hearing-event](/functions/src/notifications/images/example-scraped_hearing-event.png)
+Example event regarding an testimony:
+![example-testimony-notification-event](/functions/src/notifications/images/example-testimony-notification-event.png)
 
 ### Cloud Functions
 
 The following cloud functions are involved in the notification process:
 
-1. **publishNotifications**:
+1. **populateBillHistoryNotifictionEvents** and **populateTestimonySubmissionNotificationEvents**:
+
+   - Creates/Updates a notificationEvent document when:
+     - A Bill is created or updated, if the history is updated, it will update the notificationEvent history and not create a new one.
+     - Testimony is published or updated, if the testimony content is updated, it will update the notificationEvent testimony content an not create a new one.
 
-   - Creates a notification document from an event.
+2. **publishNotifications**:
+
+   - Creates a notification document from an notification event.
    - Populates the user's `userNotificationFeed` collection with a notification document.
    - Populates the newsfeed.
 
    For example, here is a notification document in a given user's feed:
 
-![example-org-notification](/functions/src/notifications/images/example-org-notification.png)
+![example-bill-history-update-notification](/functions/src/notifications/images/example-bill-history-update-notification.png)
+
+- There are two key fields to differentiate whether a notification came from following a bill or following a user/organization:
+  - `isBillMatch` and `isUserMatch` indicate the source of the notification.
+    - For example, if a user follows both a bill and an organization, and the organization posts testimony to that same bill, both `isBillMatch` and `isUserMatch` will be true.
+    - If a user follows only the bill and not the organization, `isBillMatch` will be true and `isUserMatch` will be false, and vice versa.
 
-1. **deliverNotifications**:
+3. **deliverNotifications**:
 
    - Sends notifications to users who have a `notificationFrequency` of 'daily' and whose `nextDigestAt` is less than or equal to the current time.
    - Populates the `emails` collection with a notification document.
 
-2. **cleanUpNotifications**:
+4. **cleanUpNotifications**:
    - Removes notifications from the users' userNotificationFeed collection that are older than 60 days.
    - Removes notifications from the notificationEvents collection that are older than 60 days.
    - Removes notifications from the emails collection that are older than 60 days.
@@ -54,6 +68,7 @@ The following cloud functions are involved in the notification process:
 - `activeTopicSubscriptions`: Stores the active topic subscriptions for users.
 - `emails`: Stores the notification mails sent to users.
 - `notificationEvents`: Stores the events that trigger notifications.
+- `userNotificationFeed`: Stores the notifications for each user
 
 ### Query Logic
 
@@ -67,6 +82,12 @@ To test these functions in a container environment, use the following command:
 yarn firebase-admin -e local run-script <name-of-script>
 ```
 
+or to test the notifications as a whole
+
+```bash
+yarn test:integration notifications.test.ts
+```
+
 ## Future Considerations
 
 - `publishNotifications` currently listens to the `notificationEvents` collection but could be extended to include other collections.

functions/src/notifications/images/example-bill-event.png

@@ -1,6 +1,6 @@
 // Sets up a document trigger for /events and queries the activeTopicSubscriptions collection group in Firestore
 // for all subscriptions for the given topic event, then creates a notification document in the user's notification feed.
-// This function runs every time a new topic event is created in the /events collection.
+// This function runs every time a new topic event is created in the /notificationEvents collection.
 // Creates a notification document in the user's notification feed for each active subscription.
 
 // Import necessary Firebase modules