Update with link to BAT design history

guides/adr/0012-formalize-accredited-provider-relationships.md

@@ -8,24 +8,29 @@ Proposal
 
 ## Context
 
-We have a database table `provider` that has an implicit self-join relationship based on another column `accrediting_provider`.
 
-The relationship that currently exists is unconventional with respect to a normalised relational database.
+### Evolving provider relationships
+The structural and conceptual relationships among and between providers and users has changed in many ways since this codebase was started.[[1]]
 
-Making the relationship more conventional will allow us to query, validate and enforce the relationships easily and will reduce the uncertainty about the nature of this relationship.
+Providers have always had a relationship between one another in the form of course accreditation. More recently, this relationship has been extended to delegating this accreditation.
 
+We have Accredited provider relationships that exist solely for organisational reasons. This happens when Accredited provider A1 is an accredited provider for provider A2 but there is no expectation or intention for A1 to be the accredited provider for courses run by A2. This feels like an abuse of the accredited provider association, or a mislabelling of the relationship.
 
-### Organisations
+### Unconventional entity associations
 
-Publish used to employ a system of Organisations. A number of Providers would be grouped by all being a member of an organisation. 
-Users would also be members of the organisation.
+We have a database table `provider` that has an implicit self-join relationship based on another column `accrediting_provider`.
+The association exists through a column called `accredited_provider_enrichments`.
+
+The relationship that currently exists is unconventional with respect to a normalised relational database.
 
+This is explained more in [Option 1](#1.-leave-the-relationships-as-they-are).
 
 
+### Organisations
 
-### Misuse of the existing relationships
+Publish used to employ a system of 'Organisations'. A number of Providers would be grouped by all being a member of an organisation. 
+Users would also be members of the organisation. This architecture has been abandoned but there are still remnants of this system in the codebase.
 
-We have seen Accredited provider relationships that exist solely for organisational reasons. This happens when Accredited provider A1 is an accredited provider for provider A2 but there is no expectation or intention for A1 to be the accredited provider for courses run by A2. This feels like an abuse of the accredited provider association.
 
 ### Definitions
 
@@ -34,12 +39,15 @@ We have seen Accredited provider relationships that exist solely for organisatio
      * |or|
      * A provider that has an subordinate assocation to another provider (accredited).
  - An Accredited Provider
-     * A provider that has an authoratative assocation to another provider (training).
+     * A provider that has an authoritative association to another provider (training).
  - Accrediting Provider
      * A provider that accredits one or more courses on behalf of one or more training provider.
  - An Accredited Provider Relationship
      * A directional association between an accredited provider and another provider.
+ - Lead partner
+     * This concept does not exist in the codebase
 
+### In the codebase
 An Accredited provider can run training courses, meaning they are a training provider and an accredited provider.
 
 An Accredited provider can be accredited by another accredite provider.
@@ -215,8 +223,8 @@ class Course < ApplicationRecord
 
 #### Cons
 
-- Consuses eases burden of onboarding developers
-- Leaves the data in an under contrained state
+- Eases the burden of onboarding developers
+- Leaves the data in an under constrained state
 - Inefficient methods for querying entity relationships
 
 ### 2. Create typical self-join has_many through pivot table relationship
@@ -240,6 +248,9 @@ class Provider < ApplicationRecord
            through: :training_accreditations,
            source: :training_provider,
            class_name: 'Provider'
+
+class ProviderAccreditation < ApplicationRecord
+
 ```
 
 #### Pros
@@ -248,7 +259,7 @@ class Provider < ApplicationRecord
 - Index the columns used to make these queries.
 - More formally distinguish accredited and accrediting providers.
 - Database validations (if desired) on which accredited providers can accredit which courses.
-- Opportunity to clarify definintions and understand how we are using them.
+- Opportunity to clarify definitions and understand how we are using them.
 
 #### Cons
 
@@ -288,10 +299,52 @@ class Course < ApplicationRecord
 
 - None!
 
+### 4. Introduce the Lead partner delegation concept
+
+```ruby
+class Provider < ApplicationRecord
+  has_many :accredited_accreditations,
+           class_name: 'ProviderAccreditation',
+           foreign_key: :training_provider_id
+
+  has_many :training_accreditations,
+           class_name: 'ProviderAccreditation',
+           foreign_key: :accredited_provider_id
+
+  has_many :accredited_providers,
+           through: :accredited_accreditations,
+           source: :accredited_provider,
+           class_name: 'Provider'
+
+  has_many :training_providers,
+           through: :training_accreditations,
+           source: :training_provider,
+           class_name: 'Provider'
+```
+
+#### Pros
+
+- Query the training provider / accredited provider relationships through typical relational associations
+- Index the columns used to make these queries.
+- More formally distinguish accredited and accrediting providers.
+- Database validations (if desired) on which accredited providers can accredit which courses.
+- Opportunity to clarify definitions and understand how we are using them.
+
+#### Cons
+
+- None!
+
+
 ## Decision
 
 The change option that we're proposing or have agreed to implement.
 
 ## Consequences
 
 What becomes easier or more difficult to do and any risks introduced by the change that will need to be mitigated.
+
+## Resources:
+
+[1]: https://becoming-a-teacher.design-history.education.gov.uk/becoming-a-teacher/understanding-the-relationships-between-organisations-delivering-initial-teacher-training/
+
+