Merge pull request #329 from GSA/stvnrlly/agreement-adr

Add agreement model ADR

docs/adrs/0005-agreement-data-model.md

@@ -0,0 +1,136 @@
+# TITLE: Agreement info in data model
+
+
+| CREATED DATE | LAST UPDATED | STATUS | AUTHOR | STAKEHOLDERS |
+| :---: | :---: | :---: | :---: | :---: |
+| 06/21/2023 | 07/05/2023 | Accepted | @stvnrlly, @ccostino | @GSA/notify-contributors |
+
+
+## CONTEXT AND PROBLEM STATEMENT
+
+**OPEN ISSUE(S):**
+* https://github.com/GSA/notifications-api/issues/141
+* https://github.com/GSA/notifications-admin/issues/53
+* https://github.com/GSA/notifications-admin/issues/51
+
+We will be entering into Memoranda of Understanding (MOU) and Interagency
+Agreements (IAA) with partner agencies. Data from those agreements will be
+important for application function.
+
+Unlike the UK version of the application, users will not be able to complete a
+self-service in-app agreement process. Our agreement process requires that
+documents be “signed” outside of the application and (especially in the case of
+an IAA) needs to happen with specific forms that have historically proven
+difficult to automate.
+
+Inside the application, we’ll want to know information about the partner as well
+as information necessary to avoid overspending the account.
+
+This information includes:
+- Agreement identifier
+- Agreement type (MOU or IAA)
+- Agreement partner name
+- Agreement status
+- Agreement start datetime (known as period of performance)
+- Agreement end datetime (known as period of performance)
+- Agreement URL (where it is in Google Drive)
+- Budget amount (*not* message limit)
+
+
+## DECISION DRIVERS
+
+An implementation should address these needs:
+
+- The need for multiple agreements per partner over time
+- The information and tools to stop sending before overspending
+- The ability to connect data to organization and service models
+
+This is a minimal implementation of agreement data. It's quite possible that
+it will change and expand over time, but those needs are not yet clear.
+
+Because we will continue to have the actual agreement docs safely in Google
+Drive, this implementation does not need to be a source of truth and does not
+need to retain history over time.
+
+
+### SECURITY COMPLIANCE CONSIDERATIONS
+
+We will need to take care about permissions to change this data. Existing
+permissions are fairly binary: you are a user or you are an admin. We should
+consider whether that's still sufficient or if an in-between role would be
+useful.
+
+
+## CONSIDERED OPTIONS
+
+As a team, we've gone through the following options:
+
+- Add an Agreement model: a new class in `models.py` with the relevant fields.
+  - Pros:
+    - Separates agreements from the orgs, since they may change separately
+    - Multiple agreement-like models might be confusing, this avoids that
+  - Cons:
+    - Groups IAA and MOU together, which makes validation at the model level
+      harder and, in turn, makes it easier to break validation logic elsewhere
+      in the application
+
+- Add MOU and IAA models: two new classes in `models.py` with the same fields
+  but different configurations.
+  - Pros:
+    - Cleanest representation of the real world
+    - Allows SQL-level support for required/unique fields
+  - Cons:
+    - Most complex data model
+
+- Add agreement info to Organization model: no new classes, just a combination
+  of new fields and properties.
+  - Pros:
+    - No added model complexity
+  - Cons:
+    - Doesn’t directly allow for history
+
+
+## CHOSEN OPTION: Add an Agreement model
+
+By adding an Agreement model, we’ll allow flexibility in the interaction between
+agreements and organizations but stop short of attempting to recreate the full
+complexity of agreements in our data model.
+
+If we later find that it’s necessary to separate MOU and IAA agreements, we
+should be able to perform a migration.
+
+
+### Consequences
+
+- Positive
+  - We’ll gain more granular control over message limits for paid (IAA)
+    agreements
+  - We can offer more agreement transparency to users. For example, identifying
+    agreements that will need renewal
+
+- Negative
+  - We’re adding some complexity to the data model
+  - We know that this implementation is an MVP and thus might have rough edges
+  - Manual work is necessary to keep agreements in sync with the real-world
+    process
+
+
+## VALIDATION AND NEXT STEPS
+
+This process includes adding the new model and updating the existing models to
+use them.
+
+1. Add the new model:
+   - Add Agreement to models.py with the fields identified above
+   - Create migration to add/update table
+
+2. Update the Organisation model:
+   - Add one-to-many field linking one Organisation to multiple Agreements
+   - Add model property to convert budget amount into message limit
+   - Add model property to provide remaining budget based on sent messages
+   - Add model property about whether free tier or not
+   - Add model property for free tier usage (retrieve messages sent in a year)
+
+This will set up a new system, but stops short of connecting agreements to the
+services actually sending the messages. This approach will be laid out in a
+forthcoming ADR about managing message limits.

docs/adrs/README.md

@@ -172,6 +172,7 @@ top!).
 
 | ADR | TITLE | CURRENT STATUS | IMPLEMENTED | LAST MODIFIED |
 | :---: | :---: | :---: | :---: | :---: |
+| [ADR-0005](./0005-agreement-data-model.md) | [Agreement info in data model](./0005-agreement-data-model.md) | Accepted | No | 07/05/2023 |
 | [ADR-0004](./0004-designing-pilot-content-visibility.md) | [Designing Pilot Content Visibility](./0004-designing-pilot-content-visibility.md) | Proposed | No | 06/20/2023 |
 | [ADR-0003](./0003-implementing-invite-expirations.md) | [Implementing User Invite Expirations](./0003-implementing-invite-expirations.md) | Proposed | No | 06/15/2023 |
 | [ADR-0002](./0002-how-to-handle-timezones.md) | [Determine How to Handle Timezones in US Notify](./0002-how-to-handle-timezones.md) | Accepted | Yes | 06/15/2023 |