openedx-plugin-sample 3.0.1__tar.gz → 3.2.0__tar.gz

{openedx_plugin_sample-3.0.1 → openedx_plugin_sample-3.2.0}/.annotation_safe_list.yml

@@ -39,3 +39,11 @@ waffle.Sample:
   ".. no_pii:": "This model has no PII"
 waffle.Switch:
   ".. no_pii:": "This model has no PII"
+openedx_catalog.CatalogCourse:
+  ".. no_pii:": "This model has no PII"
+openedx_catalog.CourseRun:
+  ".. no_pii:": "This model has no PII"
+organizations.HistoricalOrganization:
+  ".. no_pii:": "This model has no PII"
+organizations.HistoricalOrganizationCourse:
+  ".. no_pii:": "This model has no PII"

{openedx_plugin_sample-3.0.1 → openedx_plugin_sample-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openedx-plugin-sample
-Version: 3.0.1
+Version: 3.2.0
 Summary: A sample backend plugin for the Open edX Platform
 Author-email: Open edX Project <oscm@openedx.org>
 License-Expression: Apache-2.0
@@ -21,6 +21,7 @@ Requires-Dist: Django
 Requires-Dist: djangorestframework
 Requires-Dist: django-filter
 Requires-Dist: edx-opaque-keys
+Requires-Dist: openedx-core
 Requires-Dist: openedx-events
 Requires-Dist: openedx-filters
 Requires-Dist: openedx-atlas
@@ -212,40 +213,62 @@ def perform_create(self, serializer):
 
 ### Event Handler Example
 
+This plugin reacts to `COURSE_ENROLLMENT_CHANGED` to unarchive a course on the
+learner's dashboard when they upgrade to the verified track. The idea: a learner
+who has previously archived a course shouldn't have to dig it back out of their
+"Archived" section after upgrading -- their renewed investment is a strong
+signal that the course belongs back in their active list.
+
 ```python
-from openedx_events.content_authoring.signals import COURSE_CATALOG_INFO_CHANGED
+from openedx_events.learning.data import CourseEnrollmentData
+from openedx_events.learning.signals import COURSE_ENROLLMENT_CHANGED
 from django.dispatch import receiver
 
-@receiver(COURSE_CATALOG_INFO_CHANGED)
-def log_course_info_changed(signal, sender, catalog_info: CourseCatalogData, **kwargs):
-    logging.info(f"{catalog_info.course_key} has been updated!")
-    # Add your custom business logic here
+@receiver(COURSE_ENROLLMENT_CHANGED)
+def unarchive_on_verified_upgrade(signal, sender, enrollment: CourseEnrollmentData, **kwargs):
+    if not enrollment.is_active or enrollment.mode != "verified":
+        return
+    CourseArchiveStatus.objects.filter(
+        user_id=enrollment.user.id,
+        course_id=enrollment.course.course_key,
+        is_archived=True,
+    ).update(is_archived=False, archive_date=None)
 ```
 
+**Why an event (not a filter)?** The unarchive is a *one-time nudge*: if the
+learner re-archives the course later, we respect that. Implementing this as a
+continuous rule in the filter pipeline (e.g. "any verified course is never
+archived") would override the learner's intent. Events fire at the moment a
+state change happens, which is exactly when this kind of one-shot reaction
+belongs.
+
 ### Available Events
 
 **Event Catalog**: [Open edX Events Reference](https://docs.openedx.org/projects/openedx-events/en/latest/reference/events.html)
 
 **Common Events:**
-- `COURSE_CATALOG_INFO_CHANGED` - Course information updated
+- `COURSE_ENROLLMENT_CHANGED` - Enrollment becomes active/inactive or changes mode
+- `COURSE_ENROLLMENT_CREATED` - Student newly enrolled in a course
 - `STUDENT_REGISTRATION_COMPLETED` - New user registered
 - `CERTIFICATE_CREATED` - Certificate generated for learner
-- `ENROLLMENT_CREATED` - Student enrolled in course
+- `COURSE_CATALOG_INFO_CHANGED` - Course catalog metadata updated
 
 ### Event Data Structure
 
-Each event includes specific data. For `COURSE_CATALOG_INFO_CHANGED`:
+Each event includes a specific data object. For `COURSE_ENROLLMENT_CHANGED`:
 
 ```python
-def log_course_info_changed(signal, sender, catalog_info: CourseCatalogData, **kwargs):
-    # catalog_info contains:
-    # - course_key: CourseKey object
-    # - name: Course display name
-    # - schedule: Course schedule information
-    # - hidden: Visibility status
+def unarchive_on_verified_upgrade(signal, sender, enrollment: CourseEnrollmentData, **kwargs):
+    # enrollment contains:
+    # - user: UserData (with .id, .is_active, .pii)
+    # - course: CourseData (with .course_key, .display_name, .start, .end)
+    # - mode: str (e.g. "audit", "verified", "honor")
+    # - is_active: bool
+    # - creation_date: datetime
+    # - created_by: UserData (optional)
 ```
 
-**Key Point**: Check the [event definition](https://docs.openedx.org/projects/openedx-events/en/latest/reference/events.html) to understand what data is available.
+**Key Point**: Check the [event data reference](https://docs.openedx.org/projects/openedx-events/en/latest/reference/data.html) to understand the exact fields available for each event.
 
 ### Signal Handler Registration
 
@@ -499,15 +522,19 @@ const response = await client.get(
 );
 ```
 
-### Events + API Integration
+### Events + Models Integration
 
 ```python
-@receiver(COURSE_CATALOG_INFO_CHANGED)
-def sync_course_archive_on_change(signal, sender, catalog_info, **kwargs):
-    # Update archive statuses when course info changes
+@receiver(COURSE_ENROLLMENT_CHANGED)
+def unarchive_on_verified_upgrade(signal, sender, enrollment, **kwargs):
+    # React to a verified upgrade by clearing the learner's archive flag
+    if not enrollment.is_active or enrollment.mode != "verified":
+        return
     CourseArchiveStatus.objects.filter(
-        course_id=catalog_info.course_key
-    ).update(last_synced=timezone.now())
+        user_id=enrollment.user.id,
+        course_id=enrollment.course.course_key,
+        is_archived=True,
+    ).update(is_archived=False, archive_date=None)
 ```
 
 ### Filters + Settings Integration

{openedx_plugin_sample-3.0.1 → openedx_plugin_sample-3.2.0}/README.md

@@ -184,40 +184,62 @@ def perform_create(self, serializer):
 
 ### Event Handler Example
 
+This plugin reacts to `COURSE_ENROLLMENT_CHANGED` to unarchive a course on the
+learner's dashboard when they upgrade to the verified track. The idea: a learner
+who has previously archived a course shouldn't have to dig it back out of their
+"Archived" section after upgrading -- their renewed investment is a strong
+signal that the course belongs back in their active list.
+
 ```python
-from openedx_events.content_authoring.signals import COURSE_CATALOG_INFO_CHANGED
+from openedx_events.learning.data import CourseEnrollmentData
+from openedx_events.learning.signals import COURSE_ENROLLMENT_CHANGED
 from django.dispatch import receiver
 
-@receiver(COURSE_CATALOG_INFO_CHANGED)
-def log_course_info_changed(signal, sender, catalog_info: CourseCatalogData, **kwargs):
-    logging.info(f"{catalog_info.course_key} has been updated!")
-    # Add your custom business logic here
+@receiver(COURSE_ENROLLMENT_CHANGED)
+def unarchive_on_verified_upgrade(signal, sender, enrollment: CourseEnrollmentData, **kwargs):
+    if not enrollment.is_active or enrollment.mode != "verified":
+        return
+    CourseArchiveStatus.objects.filter(
+        user_id=enrollment.user.id,
+        course_id=enrollment.course.course_key,
+        is_archived=True,
+    ).update(is_archived=False, archive_date=None)
 ```
 
+**Why an event (not a filter)?** The unarchive is a *one-time nudge*: if the
+learner re-archives the course later, we respect that. Implementing this as a
+continuous rule in the filter pipeline (e.g. "any verified course is never
+archived") would override the learner's intent. Events fire at the moment a
+state change happens, which is exactly when this kind of one-shot reaction
+belongs.
+
 ### Available Events
 
 **Event Catalog**: [Open edX Events Reference](https://docs.openedx.org/projects/openedx-events/en/latest/reference/events.html)
 
 **Common Events:**
-- `COURSE_CATALOG_INFO_CHANGED` - Course information updated
+- `COURSE_ENROLLMENT_CHANGED` - Enrollment becomes active/inactive or changes mode
+- `COURSE_ENROLLMENT_CREATED` - Student newly enrolled in a course
 - `STUDENT_REGISTRATION_COMPLETED` - New user registered
 - `CERTIFICATE_CREATED` - Certificate generated for learner
-- `ENROLLMENT_CREATED` - Student enrolled in course
+- `COURSE_CATALOG_INFO_CHANGED` - Course catalog metadata updated
 
 ### Event Data Structure
 
-Each event includes specific data. For `COURSE_CATALOG_INFO_CHANGED`:
+Each event includes a specific data object. For `COURSE_ENROLLMENT_CHANGED`:
 
 ```python
-def log_course_info_changed(signal, sender, catalog_info: CourseCatalogData, **kwargs):
-    # catalog_info contains:
-    # - course_key: CourseKey object
-    # - name: Course display name
-    # - schedule: Course schedule information
-    # - hidden: Visibility status
+def unarchive_on_verified_upgrade(signal, sender, enrollment: CourseEnrollmentData, **kwargs):
+    # enrollment contains:
+    # - user: UserData (with .id, .is_active, .pii)
+    # - course: CourseData (with .course_key, .display_name, .start, .end)
+    # - mode: str (e.g. "audit", "verified", "honor")
+    # - is_active: bool
+    # - creation_date: datetime
+    # - created_by: UserData (optional)
 ```
 
-**Key Point**: Check the [event definition](https://docs.openedx.org/projects/openedx-events/en/latest/reference/events.html) to understand what data is available.
+**Key Point**: Check the [event data reference](https://docs.openedx.org/projects/openedx-events/en/latest/reference/data.html) to understand the exact fields available for each event.
 
 ### Signal Handler Registration
 
@@ -471,15 +493,19 @@ const response = await client.get(
 );
 ```
 
-### Events + API Integration
+### Events + Models Integration
 
 ```python
-@receiver(COURSE_CATALOG_INFO_CHANGED)
-def sync_course_archive_on_change(signal, sender, catalog_info, **kwargs):
-    # Update archive statuses when course info changes
+@receiver(COURSE_ENROLLMENT_CHANGED)
+def unarchive_on_verified_upgrade(signal, sender, enrollment, **kwargs):
+    # React to a verified upgrade by clearing the learner's archive flag
+    if not enrollment.is_active or enrollment.mode != "verified":
+        return
     CourseArchiveStatus.objects.filter(
-        course_id=catalog_info.course_key
-    ).update(last_synced=timezone.now())
+        user_id=enrollment.user.id,
+        course_id=enrollment.course.course_key,
+        is_archived=True,
+    ).update(is_archived=False, archive_date=None)
 ```
 
 ### Filters + Settings Integration

{openedx_plugin_sample-3.0.1 → openedx_plugin_sample-3.2.0}/pyproject.toml

@@ -32,6 +32,7 @@ dependencies = [
     "djangorestframework",
     "django-filter",
     "edx-opaque-keys",
+    "openedx-core",
     "openedx-events",
     "openedx-filters",
     "openedx-atlas",

openedx_plugin_sample-3.2.0/src/openedx_plugin_sample/admin.py

@@ -0,0 +1,55 @@
+"""
+Django admin configuration for openedx_plugin_sample.
+
+This module demonstrates how to expose plugin models in the Django admin
+site provided by Open edX (LMS and CMS each have their own admin under
+``/admin/``). Defining a ``ModelAdmin`` for each model gives operators a
+ready-made UI to inspect and manage plugin data without needing custom
+tooling.
+
+Django Documentation:
+- ModelAdmin: https://docs.djangoproject.com/en/stable/ref/contrib/admin/
+"""
+
+from django.contrib import admin
+
+from openedx_plugin_sample.models import CourseArchiveStatus
+
+
+@admin.register(CourseArchiveStatus)
+class CourseArchiveStatusAdmin(admin.ModelAdmin):
+    """
+    Admin configuration for the CourseArchiveStatus model.
+    """
+
+    list_display = (
+        "course_key",
+        "user",
+        "is_archived",
+        "archive_date",
+        "updated_at",
+    )
+    list_filter = ("is_archived",)
+    # Search by the related CourseRun's course_key and the user's username/email.
+    search_fields = (
+        "course_run__course_key",
+        "user__username",
+        "user__email",
+    )
+    # FKs use raw id widgets (lookup popup) rather than a <select>, since the
+    # CourseRun and User tables can have many thousands of rows on a real
+    # Open edX deployment.
+    raw_id_fields = ("course_run", "user")
+    readonly_fields = ("created_at", "updated_at")
+    ordering = ("-updated_at",)
+
+    @admin.display(description="Course key", ordering="course_run__course_key")
+    def course_key(self, obj: CourseArchiveStatus) -> str:
+        """
+        Show the course's course_key string in list_display.
+
+        We never expose CourseRun's internal integer PK in the admin; the
+        course_key (e.g. "course-v1:edX+DemoX+Demo_Course") is the identifier
+        operators recognize.
+        """
+        return str(obj.course_run.course_key)

{openedx_plugin_sample-3.0.1 → openedx_plugin_sample-3.2.0}/src/openedx_plugin_sample/apps.py

@@ -92,8 +92,8 @@ class SamplePluginConfig(AppConfig):
         #     "lms.djangoapp": {
         #         "relative_path": "signals",
         #         "receivers": [{
-        #             "receiver_func_name": "log_course_info_changed",
-        #             "signal_path": "openedx_events.content_authoring.signals.COURSE_CATALOG_INFO_CHANGED",
+        #             "receiver_func_name": "unarchive_on_verified_upgrade",
+        #             "signal_path": "openedx_events.learning.signals.COURSE_ENROLLMENT_CHANGED",
         #         }]
         #     }
         # }

openedx_plugin_sample-3.2.0/src/openedx_plugin_sample/migrations/0001_initial.py

@@ -0,0 +1,36 @@
+# Generated by Django 5.2.13 on 2026-05-14 01:13
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        ('openedx_catalog', '0001_initial'),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='CourseArchiveStatus',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('is_archived', models.BooleanField(db_index=True, default=False, help_text='Whether the course is archived.')),
+                ('archive_date', models.DateTimeField(blank=True, help_text='The date and time when the course was archived.', null=True)),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('course_run', models.ForeignKey(help_text='The course run that this archive status is for.', on_delete=django.db.models.deletion.CASCADE, related_name='archive_statuses', to='openedx_catalog.courserun')),
+                ('user', models.ForeignKey(help_text='The user who this archive status is for.', on_delete=django.db.models.deletion.CASCADE, related_name='course_archive_statuses', to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'verbose_name': 'Course Archive Status',
+                'verbose_name_plural': 'Course Archive Statuses',
+                'ordering': ['-updated_at'],
+                'constraints': [models.UniqueConstraint(fields=('course_run', 'user'), name='unique_user_course_archive_status')],
+            },
+        ),
+    ]

{openedx_plugin_sample-3.0.1 → openedx_plugin_sample-3.2.0}/src/openedx_plugin_sample/models.py

@@ -4,7 +4,7 @@ Database models for openedx_plugin_sample.
 
 from django.contrib.auth import get_user_model
 from django.db import models
-from opaque_keys.edx.django.models import CourseKeyField
+from openedx_catalog.models import CourseRun
 
 
 class CourseArchiveStatus(models.Model):
@@ -16,8 +16,11 @@ class CourseArchiveStatus(models.Model):
     .. no_pii: This model does not store PII directly, only references to users via foreign keys.
     """
 
-    course_id = CourseKeyField(
-        max_length=255, db_index=True, help_text="The unique identifier for the course."
+    course_run = models.ForeignKey(
+        CourseRun,
+        on_delete=models.CASCADE,
+        related_name="archive_statuses",
+        help_text="The course run that this archive status is for.",
     )
 
     user = models.ForeignKey(
@@ -47,7 +50,9 @@ class CourseArchiveStatus(models.Model):
         Return a string representation of the course archive status.
         """
         # pylint: disable=no-member
-        return f"{self.course_id} - {self.user.username} - {'Archived' if self.is_archived else 'Not Archived'}"
+        # Identify the course by its course_key string, never by the internal PK.
+        archived = "Archived" if self.is_archived else "Not Archived"
+        return f"{self.course_run.course_key} - {self.user.username} - {archived}"
 
     class Meta:
         """
@@ -57,9 +62,9 @@ class CourseArchiveStatus(models.Model):
         verbose_name = "Course Archive Status"
         verbose_name_plural = "Course Archive Statuses"
         ordering = ["-updated_at"]
-        # Ensure combination of course_id and user is unique
+        # Ensure combination of course_run and user is unique
         constraints = [
             models.UniqueConstraint(
-                fields=["course_id", "user"], name="unique_user_course_archive_status"
+                fields=["course_run", "user"], name="unique_user_course_archive_status"
             )
         ]

openedx_plugin_sample-3.2.0/src/openedx_plugin_sample/pipeline.py

@@ -0,0 +1,91 @@
+"""
+Open edX Filters implementation for the openedx_plugin_sample application.
+
+This module demonstrates how to use Open edX Filters to modify platform behavior
+without changing core code. Filters are part of the Hooks Extension Framework
+and allow you to intercept and modify data at specific points in the platform.
+
+What Are Open edX Filters?
+Filters are functions that can modify application behavior by altering input data
+or halting execution based on specific conditions. Unlike events (which only
+observe), filters can change what happens next in the platform.
+
+Key Concepts:
+- Filters receive data and return modified data
+- They run at specific pipeline steps during platform operations
+- Filters can halt execution by raising exceptions
+- Multiple filters can be chained together in a pipeline
+- Filters should be lightweight and handle errors gracefully
+
+Official Documentation:
+- Filters Overview: https://docs.openedx.org/projects/openedx-filters/en/latest/
+- Using Filters: https://docs.openedx.org/projects/openedx-filters/en/latest/how-tos/using-filters.html
+- Available Filters: https://docs.openedx.org/projects/openedx-filters/en/latest/reference/filters.html
+- Filter Tooling: https://docs.openedx.org/projects/openedx-filters/en/latest/reference/filters-tooling.html
+
+Registration Process:
+1. Create filter class inheriting from PipelineStep
+2. Implement run_filter() method with correct signature
+3. Register filter in Django settings OPEN_EDX_FILTERS_CONFIG
+4. Deploy and test the filter behavior
+
+Common Use Cases:
+- URL redirection and customization
+- Access control and permission checks
+- Data transformation and validation
+- Integration with external systems
+- Custom business logic implementation
+"""
+
+import logging
+
+import crum
+from openedx_filters.filters import PipelineStep
+
+from .models import CourseArchiveStatus
+
+logger = logging.getLogger(__name__)
+
+
+class AddArchiveStatusToLearnerHomeCourseRun(PipelineStep):
+    """
+    Customize each courseRun within a Learner Dashboard's /init API response to include the CourseArchiveStatus.
+    """  # noqa: E501
+
+    def run_filter(self, serialized_courserun, **kwargs):  # pylint: disable=arguments-differ
+        """
+        Insert `isArchivedByLearner` into one serialized courseRun for the Learner Home /init response.
+
+        Args:
+            serialized_courserun (dict): One courseRun from the serializer. Reads
+                `courseId` (a course key string, e.g. "course-v1:edX+DemoX+Demo_Course");
+                all other fields are passed through unchanged.
+
+        Returns:
+            dict: ``{"serialized_courserun": <updated dict>}``. The updated dict has the
+                same keys as the input plus `isArchivedByLearner` (bool) -- True iff a
+                CourseArchiveStatus row exists for the current request user and this
+                courseId with `is_archived=True`; False otherwise (including when no row
+                exists).
+
+        The current user is read from the active request via `crum`, so this filter only
+        runs meaningfully inside a request cycle. Note that `isArchivedByLearner` is
+        distinct from `isArchived`, which the platform sets based on whether the course
+        run itself has ended.
+        """  # noqa: E501
+        request = crum.get_current_request()
+        if not (request and request.user):
+            return serialized_courserun
+        try:
+            is_archived_by_learner = CourseArchiveStatus.objects.get(
+                user=request.user,
+                course_run__course_key=serialized_courserun["courseId"],
+            ).is_archived
+        except CourseArchiveStatus.DoesNotExist:
+            is_archived_by_learner = False
+        return {
+            "serialized_courserun": {
+                **serialized_courserun,
+                "isArchivedByLearner": is_archived_by_learner,
+            },
+        }

{openedx_plugin_sample-3.0.1 → openedx_plugin_sample-3.2.0}/src/openedx_plugin_sample/serializers.py

@@ -3,6 +3,7 @@ Serializers for the openedx_plugin_sample app.
 """
 
 from django.contrib.auth import get_user_model
+from openedx_catalog.models import CourseRun
 from rest_framework import serializers
 
 from openedx_plugin_sample.models import CourseArchiveStatus
@@ -21,6 +22,16 @@ class CourseArchiveStatusSerializer(serializers.ModelSerializer):
         required=False,
     )
 
+    # The model stores a FK to CourseRun, but APIs should identify courses by
+    # their full course key string (e.g. "course-v1:edX+DemoX+Demo_Course"),
+    # never by CourseRun's internal integer PK. The slug field looks up the
+    # related CourseRun by its `course_key` for both reads and writes.
+    course_id = serializers.SlugRelatedField(
+        source="course_run",
+        slug_field="course_key",
+        queryset=CourseRun.objects.all(),
+    )
+
     class Meta:
         """
         Meta class for CourseArchiveStatusSerializer.
@@ -37,3 +48,14 @@ class CourseArchiveStatusSerializer(serializers.ModelSerializer):
             "updated_at",
         ]
         read_only_fields = ["id", "created_at", "updated_at", "archive_date"]
+
+    def to_representation(self, instance):
+        """
+        Serialize the instance, casting course_id to a string.
+
+        CourseRun.course_key returns a CourseLocator (not a string), which the
+        default JSON encoder can't serialize, so we coerce to str on output.
+        """
+        data = super().to_representation(instance)
+        data["course_id"] = str(data["course_id"])
+        return data

{openedx_plugin_sample-3.0.1 → openedx_plugin_sample-3.2.0}/src/openedx_plugin_sample/settings/common.py

@@ -11,7 +11,8 @@ the main settings object. You can modify this object to add plugin-specific
 configuration that integrates seamlessly with the platform.
 
 Official Documentation:
-- Plugin Settings: https://docs.openedx.org/projects/edx-django-utils/en/latest/plugins/how_tos/how_to_create_a_plugin_app.html#plugin-settings
+- Plugin Settings:
+  https://docs.openedx.org/projects/edx-django-utils/en/latest/plugins/how_tos/how_to_create_a_plugin_app.html#plugin-settings
 - Django Settings: https://docs.djangoproject.com/en/stable/topics/settings/
 
 Settings Organization:
@@ -96,8 +97,8 @@ def _configure_openedx_filters(settings):
     filters_config = getattr(settings, 'OPEN_EDX_FILTERS_CONFIG', {})
 
     # Filter we want to register
-    filter_name = "org.openedx.learning.course_about.page.url.requested.v1"
-    our_pipeline_step = "openedx_plugin_sample.pipeline.ChangeCourseAboutPageUrl"
+    filter_name = "org.openedx.learning.home.courserun.api.rendered.started.v1"
+    our_pipeline_step = "openedx_plugin_sample.pipeline.AddArchiveStatusToLearnerHomeCourseRun"
 
     # Check if this filter already has configuration
     if filter_name in filters_config:

openedx_plugin_sample-3.2.0/src/openedx_plugin_sample/signals.py

@@ -0,0 +1,66 @@
+"""
+Open edX Events signal handlers for the openedx_plugin_sample application.
+
+This module demonstrates how to consume Open edX Events to react to platform
+activity. Events are part of the Hooks Extension Framework and provide a
+stable way to extend Open edX without modifying core code.
+
+Key Concepts:
+- Events are fired at specific points in the platform lifecycle
+- Each event delivers a structured data object (defined in openedx-events)
+- Event handlers can take action but cannot modify the event payload
+- Handlers must be imported from apps.py ready() so @receiver registers them
+
+Official Documentation:
+- Events Overview: https://docs.openedx.org/projects/openedx-events/en/latest/
+- Available Events: https://docs.openedx.org/projects/openedx-events/en/latest/reference/events.html
+- Consuming Events: https://docs.openedx.org/projects/openedx-events/en/latest/how-tos/consume-an-event.html
+- Event Data Objects: https://docs.openedx.org/projects/openedx-events/en/latest/reference/data.html
+"""
+
+import logging
+
+from django.dispatch import receiver
+from openedx_events.learning.data import CourseEnrollmentData
+from openedx_events.learning.signals import COURSE_ENROLLMENT_CHANGED
+
+from .models import CourseArchiveStatus
+
+logger = logging.getLogger(__name__)
+
+
+@receiver(COURSE_ENROLLMENT_CHANGED)
+def unarchive_on_verified_upgrade(
+    signal, sender, enrollment: CourseEnrollmentData, **kwargs
+):  # pylint: disable=unused-argument
+    """
+    Unarchive a course on the learner's dashboard when they upgrade to verified.
+
+    If a learner has previously archived a course (CourseArchiveStatus.is_archived=True)
+    and then upgrades to the verified track, the course shouldn't stay tucked away
+    in their "Archived" section -- their renewed investment in the course is a
+    strong signal that they want it back in their active list.
+
+    This is intentionally a one-time nudge, not a continuous rule: if the learner
+    re-archives the course later, we respect that choice. That's why we react to
+    the enrollment-change *event* rather than computing `isArchivedByLearner`
+    from enrollment mode in the filter pipeline.
+
+    Event reference:
+    https://docs.openedx.org/projects/openedx-events/en/latest/reference/events.html#openedx_events.learning.signals.COURSE_ENROLLMENT_CHANGED
+    """
+    if not enrollment.is_active or enrollment.mode != "verified":
+        return
+
+    updated = CourseArchiveStatus.objects.filter(
+        user_id=enrollment.user.id,
+        course_run__course_key=enrollment.course.course_key,
+        is_archived=True,
+    ).update(is_archived=False, archive_date=None)
+
+    if updated:
+        logger.info(
+            "Unarchived course %s for user %s after verified upgrade",
+            enrollment.course.course_key,
+            enrollment.user.id,
+        )