docs: [FC-0074] add details for illustrating how events work (#420)

docs/concepts/openedx-events.rst

@@ -22,17 +22,37 @@ How do Open edX Events work?
 
 Open edX Events are implemented by a class called `OpenEdxPublicSignal`_, which inherits from `Django's Signals class` and adds behaviors specific to the Open edX ecosystem. Thanks to this design, ``OpenEdxPublicSignal`` leverages the functionality of Django signals, allowing developers to apply their existing knowledge of the Django framework.
 
-The event execution process follows these steps:
+Architectural Diagram
+*********************
 
-#. An application component emits an event by calling the `send_event` method implemented by `OpenEdxPublicSignal`_.
+In this diagram, we illustrate the workflow of emitting and processing an Open edX Event:
 
-#. The class generates Open edX-specific metadata for the event on the fly, like the event version or the timestamp when the event was sent. The event receivers use this metadata during their processing.
+.. image:: ../_images/openedx-events-workflow.png
+   :alt: Open edX Events workflow
+   :align: center
 
-#. The tooling uses the `send or send_robust`_ method from Django signals under the hood. The ``send`` method is used for development and testing, while the ``send_robust`` method is used in production to ensure receivers don't raise exceptions halting the application process.
+Components
+~~~~~~~~~~
 
-#. Building on Django signals allows us to use the same `Django signals registry mechanism`_ for receiver management. This means that developers can register `signal receivers in their plugins`_ for Open edX Events in the same way they would for Django signals.
+#. Application (caller): The application component that emits the event. Developers may have emitted this event in a key section of the application logic, signaling that a specific action has occurred. E.g., a user has enrolled in a course, `triggering the COURSE_ENROLLMENT_CREATED event`_.
+#. OpenEdxPublicSignal: The class that implements all methods used to manage sending the event. As mentioned previously, this class inherits from Django's Signals class and adds Open edX-specific metadata and behaviors.
+#. Django Signals: The Django framework's built-in signal mechanism.
+#. Receiver1...ReceiverN: The components that listen to the event and execute custom logic in response. This receivers are implemented as Django signal receivers.
 
-#. The event is sent to all registered receivers, which are executed in the order they were registered. Each receiver processes the event data and performs the necessary actions.
+Workflow
+~~~~~~~~
+
+#. An application (caller) emits an event by calling the `send_event`_ method implemented by `OpenEdxPublicSignal`_ which the event inherits from.
+
+#. The caller passes the :term:`event payload<Event Payload>` to the `send_event`_ method. The event payload is the data associated with the event that is passed to the receivers when it's triggered, and uses data attribute classes (e.g. ``CourseEnrollmentData``, ``UserData``, etc.) to carry data about the event.
+
+#. The `send_event`_ method generates Open edX-specific metadata for the event on the fly, like the event version or the timestamp when the event was sent. The event receivers can access this metadata during their processing.
+
+#. After, the `send_event`_ method calls the `send or send_robust`_ method from Django Signals under the hood. The ``send`` method is used for development and testing, while the ``send_robust`` method is used in production to ensure receivers don't raise exceptions halting the application process.
+
+#. Building on Django Signals allows us to use the same `Django signals registry mechanism`_ for receiver management. This means that developers can register `signal receivers in their plugins`_ for Open edX Events in the same way they would for Django signals.
+
+#. All registered receivers are executed in the order they were registered. Each receiver processes the event data and performs the necessary actions.
 
 #. After all receivers for the event have been executed, the process continues with the application logic.
 
@@ -53,9 +73,8 @@ How are Open edX Events used?
 
 Developers can listen to Open edX Events by registering signal receivers from their Open edX Django plugins that respond to the emitted events. This is done using Django's signal mechanism, which allows developers to listen for events and execute custom logic in response.
 
-For more information on using Open edX Events, refer to the `Using Open edX Events`_ how-to guide.
+For more information on using Open edX Events, refer to the :doc:`../how-tos/using-events` how-to guide.
 
-.. _Using Open edX Events: ../how-tos/using-events.html
 .. _Django Signals Documentation: https://docs.djangoproject.com/en/4.2/topics/signals/
 .. _triggering the COURSE_ENROLLMENT_CREATED event: https://github.com/openedx/edx-platform/blob/master/common/djangoapps/student/models/course_enrollment.py#L777-L795
 .. _course_enrollment_post_save receiver: https://github.com/openedx/edx-platform/blob/master/openedx/core/djangoapps/notifications/handlers.py#L38-L53

docs/reference/glossary.rst

@@ -6,7 +6,7 @@ An event has multiple components that are used to define, trigger, and handle th
 .. glossary::
 
     Event Receiver
-      An event receiver, handler, or listener is a function that listens for a specific event and executes custom logic in response to the event being triggered. Since Events are Django-signals, then receivers are registered with the signal dispatcher and are called when the event is emitted. In Django, event receivers are known as signal handlers. Both terms are used interchangeably.
+      An event receiver, handler, or listener is a function that listens for a specific event and executes custom logic in response to the event being triggered. Since Events are Django-signals, then receivers are registered with the signal dispatcher and are called when the event is emitted. In Django, event receivers are known as signal receivers. Both terms can be used interchangeably. E.g., a receiver that listens for the ``COURSE_ENROLLMENT_CREATED`` event and creates a notification preference for the user.
 
     Event Trigger
       An event trigger is the action that causes an event to be emitted. When a trigger action occurs, the associated event is emitted, and any registered event receivers are called to handle the event. For example, when a user enrolls in a course, the ``COURSE_ENROLLMENT_CREATED`` event is triggered. In this case, the event trigger is the user enrolling in the course.
@@ -15,7 +15,7 @@ An event has multiple components that are used to define, trigger, and handle th
       The event payload is the data associated with an event that is passed to event receivers when it's triggered. The payload of an event are data attribute classes (e.g. ``CourseEnrollmentData``, ``UserData``, etc.) that carry data about the event such as the event name, timestamp, and any additional metadata and information about the actual event. For more information, see the `Events Payload ADR`_.
 
     Event Type
-      The event type is a unique identifier for an event that distinguishes it from other events. For example, ``org.openedx.content_authoring.xblock.published.v1``. The event type is used to identify the event, its purpose, and version. In the event bus context, the event type is used to connect events to the appropriate topics in the ``EVENT_BUS_PRODUCER_CONFIG``.
+      The event type is a unique identifier for an event that distinguishes it from other events. For example, ``org.openedx.content_authoring.xblock.published.v1``. The event type is used to identify the event, its purpose, and version. In the event bus context, the event type is used to connect events to the appropriate topics in the ``EVENT_BUS_PRODUCER_CONFIG``. E.g., the event type ``org.openedx.learning.course.enrollment.created.v1`` is used to identify the ``COURSE_ENROLLMENT_CREATED`` event.
 
     Event Definition
       An event is a signal that is emitted when a specific action occurs in the platform. The event definition is the instantiation of the ``OpenEdxPublicSignal`` class that defines the structure and metadata of an event. This definition includes information such as the event name, description, payload, and version. Event definitions are used to create events which are later imported into the services and are triggered by using the ``send_event`` method.