Skip to content

docs: add arch decision record for the replication-based migration of legacy user grouping mechanisms #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
BryanttV wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

docs: add arch decision record for the replication-based migration of legacy user grouping mechanisms #5

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
614ff44
docs: add replication of legacy mechanisms behavior ADR
BryanttV May 30, 2025
dd44eda
docs: update title and improve the sections content
BryanttV Jun 3, 2025
e66886e
chore: address PR review
BryanttV Jul 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added docs/_images/behavior-replication-phases.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
109 changes: 109 additions & 0 deletions docs/decisions/0006-replication-of-legacy-mechanisms-behavior.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
0006. Replication-Based Migration of Legacy User Grouping Mechanisms
####################################################################

Status
******

**Draft** - 2025-06-03

Context
Copy link
Member

@mariajgrimaldi mariajgrimaldi Jun 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we include here what requirements we're looking to fulfill with this migration?

  • Maintainability
  • Efficiency
  • and so on

Copy link
Author

@BryanttV BryanttV Jul 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added more details to the context based on what you mentioned, thanks!

*******

The new unified user grouping system introduced in Open edX is intended to replace the existing grouping mechanisms (cohorts, teams, and course groups) without depending on them directly. To achieve this, a behavior replication strategy was selected: implement, within the new model, the observable functionalities currently provided by legacy mechanisms, but without maintaining synchronization with their internal structures.

This migration aims to fulfill several key requirements for the long-term sustainability of the platform:

- **Maintainability**: Reduce complexity and technical debt by removing redundant and outdated implementations.
- **Extensibility**: Enable the definition of new grouping criteria and behaviors without being constrained by legacy data models or logic.
- **Consistency**: Unify the logic and storage of user grouping to ensure a predictable and coherent behavior across platform features.
- **Efficiency**: Simplify system interactions and avoid the performance and reliability costs of maintaining synchronization layers.
- **Modularity**: Decouple grouping logic from specific platform features to allow reuse across content gating, messaging, discussions, and analytics.

The proposal is organized into four phases to enable a progressive, safe, and decoupled transition from legacy code. Each phase includes specific technical decisions to ensure that the new model can fully assume the responsibilities of the legacy mechanisms without requiring synchronization between systems.

Decision
Copy link
Member

@mariajgrimaldi mariajgrimaldi Jun 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd also include the following decisions, -after refining them-:

  • Divide the migration into 4 phases, each with its own technical goals mention the goals of each phase and the expected outcome. Also, we can attach the diagram for the migration timeline we envisioned.
  • The new system must not clash with legacy systems, i.e., not only the model is independent. This means for example building a new content gating plugin for user groups, instead of building on top of the cohort/enrollment track content gating functionality.
  • We must not only replicate but also improve the logic when necessary for long-term maintainability
  • Prioritize extensibility and maintainability when possible, trying to implement the new system in a way that adding new functionalities is not a high-coupled task

Copy link
Contributor

@bmtcril bmtcril Jul 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Have we explicitly looked at using the "openedx.user_partition_scheme" plugin mechanism to implement content gating? That seems like one place we would want to continue to rely on a legacy system.

Copy link
Author

@BryanttV BryanttV Jul 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mariajgrimaldi, thanks for your suggestions! I included the additional decisions.

@bmtcril Yes, in the POC, we're currently using the "openedx.user_partition_scheme" plugin mechanism to implement content gating in the new system.

********

- The new user grouping system will operate independently from the legacy mechanisms and will not rely on their data, APIs, or behaviors.
- The behavior of legacy mechanisms will be functionally replicated in the new system.
- The migration will be divided into four clearly defined phases, each with specific technical goals and expected outcomes:

- **Phase 1** focuses on implementing the core infrastructure of the new user grouping system, supporting static (manual) groups and laying the foundation for future extensions.
- **Phase 2** introduces support for dynamic groups and replicates the functional behavior of legacy mechanisms, enabling both systems to coexist temporarily without conflicts.
- **Phase 3** completes the transition by removing the legacy code, making the new system the only active user grouping source.
- **Phase 4** finalizes the migration by delivering a centralized administrative interface that consolidates all user group management, replacing temporary or legacy UI elements.
- The new user grouping system must not only use a separate data model but also remain operationally decoupled from legacy systems. For example, features such as content gating will use new plugins based on user groups rather than extending cohort or enrollment track logic.
- The new user grouping system will be gated behind feature flags that allow it to be enabled or disabled at the instance, organization, or course level. This provides platform operators with control over rollout, adoption, and potential mitigation of performance issues. These flags will be available from the early phases and may be retained temporarily after general rollout as a safeguard during stabilization.
- When replicating legacy behaviors, improvements should be made where appropriate to support long-term maintainability. Legacy logic should not be copied as-is if it introduces known issues or technical debt.
- Design decisions should prioritize extensibility and maintainability, aiming for low coupling and high cohesion so that new grouping-related features can be added without deep refactoring.
- Once all functionalities have been replicated (dynamic groups, mutual exclusivity, content access restriction, support for divided discussions, support for ORA assignments, hierarchical structures), the legacy mechanisms will be removed and group management will migrate to a centralized administrative interface. Any legacy behavior that cannot be replicated without compromising the maintainability or design principles of the new system will be reconsidered, redesigned, or removed accordingly.

Consequences
************

- It will be possible to validate that the new system can fully replace the legacy mechanisms, without requiring synchronization or coupling.
- The migration can proceed in a safe and controlled manner, with both implementations coexisting temporarily.
- Existing group data from legacy mechanisms will not be migrated into the new system. The courses that require new grouping behavior must explicitly define groups using the new system. This ensures legacy mechanisms can be sunset cleanly without introducing data integrity risks or transformation logic.

Phases
******

.. figure:: ../_images/behavior-replication-phases.png
:alt: Behavior replication phases
:align: center
:width: 100%

Phase 1: Implementation of the new user grouping system
Copy link
Member

@mariajgrimaldi mariajgrimaldi Jun 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we add the phases diagram here?

Copy link
Author

@BryanttV BryanttV Jul 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Of course! I added the diagram.

=======================================================

- A new user grouping model will be implemented with its corresponding entities, allowing the creation of manual (static) groups.
- Only group creation and management via direct user assignment will be supported in this phase.
- Dynamic user groups based on criteria are not included in this phase.
- The system will be deployed behind a feature flag, and a temporary management interface will be exposed via the instructor dashboard.
- There will be no interaction or synchronization with the legacy mechanisms.

Phase 2: Behavior replication of legacy mechanisms functionalities
==================================================================

The unified user grouping system will be extended to support dynamic groups based on criteria and replicate the key functionalities of the legacy mechanisms (cohorts, teams, and course groups). During this phase, both systems will coexist without interference. Functionality will be implemented incrementally, focusing on one functionality at a time.

Functionalities included in this phase:
Copy link
Member

@mariajgrimaldi mariajgrimaldi Jun 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I'm missing how the unified system can support a few of these functionalities. For example:

  • Support for divided discussions: divided discussions are assigned to each group or to a group collection? This will depend on whether mutual exclusivity matters.
  • Support for ORA assignments: Same question applies to this.

Copy link
Author

@BryanttV BryanttV Jul 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we look at the current behavior:

  • Divided discussions work with Cohorts. As we know, Cohorts enforce mutual exclusivity. In contrast, user groups in the unified system are not mutually exclusive, unless they belong to a Group Collection. Initially, the idea was to assign discussions directly to individual user groups (as done in the POC), but we could consider assigning them to Group Collections instead.

  • ORA assignments currently work with Team Sets. Any team belonging to the same Team Set can submit a response to the assignment. Based on that model, we could adopt a similar approach where all user groups within a Group Collection are allowed to respond to the ORA assignment.

What do you think about this approach?


- **Support for dynamic groups:** Groups can be created manually or generated automatically based on criteria, enabling greater flexibility.
- **Mutual exclusivity:** Groups defined within a group collection must not share users.
- **Content access restriction:** Units or components can be made visible only to users in specific groups.
- **Support for divided discussions:** Users can only see and participate in discussion threads assigned to their group.
- **Support for ORA assignments:** Assignments can be submitted only by members of designated groups.
- **Hierarchical structures:** Groups can be nested or organized into group collections, as introduced in :doc:`0004-refresh-and-consistency-framework`.

Phase 3: Removal of legacy mechanisms
=====================================

Once the replicated functionalities have been validated, the removal of legacy mechanisms will proceed gradually to ensure system stability.

This phase will be executed in the following order:

#. Course groups.
#. Cohorts.
#. Teams.

As part of this process, the following will be removed for each legacy mechanism:

- Models, signals and events related.
- LMS and Studio endpoints and views.
- Configuration and logic in legacy UI and MFEs.
- All related documentation will be updated to reflect the new architecture.

Phase 4: Migration to the new administrative panel
==================================================

- A centralized administrative interface will be developed to manage groupings at the course, organization, and platform levels.
- This new UI will replace the temporary tab in the instructor dashboard.
- It will allow users to create and edit groups, visualize grouping criteria, and perform manual or bulk assignments.
- Access to the interface will be controlled by administrative permissions.
- The documentation will be updated to reflect the new administrative panel.

References
**********

- `Behavior Replication Proposal <https://openedx.atlassian.net/wiki/x/AgDiKgE>`_
Loading