GCN

Synonym Grouping

Software Design Document

Name (s): Courey Elliott
Date: 02-26-2024

TABLE OF CONTENTS

1.0 INTRODUCTION.......................1
1.1 Purpose.....................................1
1.2 Scope......................................................................2
1.3 Overview .................................................................2
1.4 Reference Material ................................................2
1.5 Definitions and Acronyms .....................................2
2.0 SYSTEM OVERVIEW ..........................................2
3.0 SYSTEM ARCHITECTURE ................................2
3.1 Architectural Design .............................................2
3.2 Decomposition Description ...................................3
3.3 Design Rationale ...................................................4
4.0 DATA DESIGN .....................................................4
4.1 Data Description ....................................................4
4.2 Data Dictionary .....................................................4
5.0 COMPONENT DESIGN ......................................4
6.0 HUMAN INTERFACE DESIGN .........................4
6.1 Overview of User Interface ...................................4
6.2 Screen Images ........................................................5
6.3 Screen Objects and Actions ...................................5
7.0 REQUIREMENTS MATRIX ................................5
8.0 APPENDICES .......................................................5

1.0 INTRODUCTION

1.1 Purpose

The Synonym feature allows circulars to be grouped by similar events even if the eventIds are not the same. It uses the eventId that is attempted to be automatically added to the circular to associate an event with a synonym group.

If the user tries to update or create a synonym and uses an eventId that is already associated with another synonym group, the old association will be broken and the event will be related to the new synonym.

1.2 Scope

The scope of this project is a fully functional synonym grouping system.
This system will have:
One page that is an index of the existing synonyms and their members that have a link to the synonym detail page for each synonym grouping.
It will have a search on the index page to search by eventId
It will ONLY be accessible by moderator
It will have a synonym detail page where the user can edit or delete the synonym.
Editing consists of adding and/or removing eventIds from the grouping and saving changes.
It will ONLY be accessible by moderator
The Circulars index will now have an option to view circulars by synonym group.
This will be feature flagged but intended for the general population
There should be a way to drop down all the circulars in a group to make them searchable.
EventId’s are editable on the circular. Only able to be edited by moderators

1.3 Overview

1.4 Reference Material

1.5 Definitions and Acronyms

Synonym - an events that are the same as other events linked by uuid.

2.0 SYSTEM OVERVIEW

Since we are using a document store and we want to use it relationally, which it is not built for, we have to do a step in the middle when we want to link data relationally. What we will do is create a pivot table that contains the eventId from the circular and a uuid that has no other significance than it links all the synonyms in the group together.

The user will use an interface to add and/or remove eventIds from synonym groups. These synonym groups will o

3.0 SYSTEM ARCHITECTURE

3.1 Architectural Design

Synonyms are made up of a uuid that ties all the synonyms in the group together and an eventId specifying which events are part of that group.

Synonyms are stored in dynamodb and are streamed via tablestream to opensearch for searchability.

3.2 Decomposition Description

Synonyms will be stored in dynamodb as a record with a uuid (the synonym id) and the eventId of related events. Records will be streamed to opensearch for search functionality.

Synonyms will be created in dynamodb. When a synonym is created, if the moderator chooses to associate an eventId that is currently already associated with a synonym, it will break the association and will be linked with the new synonym group instead.

For every synonym, there may be multiple associated eventIds, so there will be multiple records with the same uuid, but different eventIds. This means that we need to use an index on the uuid field since it is not a primary key when we are getting all synonyms by uuid.

3.3 Design Rationale

The challenge is that dynamodb is a document store and we want to use it relatinoally. This necessitates a kind of pivot like table to associate the circulars to synonyms. The moderator can create synonym groupings, which are creating the pivot between synonym and eventId by associating events with a synonym uuid.

4.0 DATA DESIGN

4.1 Data Description

Explain how the information domain of your system is transformed into data structures.
Describe how the major data or system entities are stored, processed and organized. List
any databases or data storage items.

4.2 Data Dictionary

Synonyms

5.0 COMPONENT DESIGN

In this section, we take a closer look at what each component does in a more systematic way. If you gave a functional description in section 3.2, provide a summary of your algorithm for each function listed in 3.2 in procedural description language (PDL) or pseudocode.

If you gave an OO description, summarize each object member function for all the objects listed in 3.2 in PDL or pseudocode. Describe any local data when necessary.

6.0 HUMAN INTERFACE DESIGN

6.1 Overview of User Interface

The moderator should be able to:
Navigate to an index of existing synonyms
Create a synonym grouping
add/remove events from a synonym grouping
Delete the synonym
The user should be able to:
Navigate to the circulars index and have an option to view the circulars by synonym groupings.
Drop down all circulars in a grouping and search for key words

6.2 Screen Images

I would love these, but I do not have them.

6.3 Screen Objects and Actions

I would love these, but I do not have them.

8.0 APPENDICES

Backfill Plan:
things for courey to do:

1. look to see what happens if a circular has multiple versions
2. what happens if version 1 of a circular has one eventID and version 2 has another
3. get with dakota and go through how the version history works
4. it should ONLY show in the overview page for the group the most recent versions

what do I need in order to do the backfills:

1. test the backfills locally
2. reviews on the backfills before I run them
3. I need to know how Leo wants these run.
4. I would need to know when and how many to update the eventIds
5. we need to announce that it's going to happen in advance

• come up with the wording for the announcement
• make the PR and merge it in at the appropraite time
• determine how much before the backfill starts the announcements needs to go out

6. once approved, run the synonym slug backfill
7. once approved, run the event id backfill as determined by the team
8. once approved, run the synonym backfill to create synonyms for the events that were added that don't have one already

Plan for expanding subject matchers for currently unmatched events:

1. we're going to backfill the event ids
2. then download the archive and see what circulars don't have event ids
3. determine if they need subject matchers.
4. update the subject matcher regex
5. run the event id backfill again