doc: update the Processing page

docs/badges/index.rst

@@ -18,7 +18,7 @@ Current Badges version is highly integrated with the `Credly (by Pearson)`_ serv
     settings
     configuration
     examples
-    .. processing
+    processing
     .. collecting
     .. distribution
     .. details

docs/badges/processing.rst

@@ -1,39 +1,72 @@
 Processing
 ==========
 
-**Processing** is a process of:
+Incoming events async processing happens in a separate event bus consumer process(es).
+See the Event Bus documentation for details.
 
-- Open edX `public signals` subscription
-- badge template requirements analysis
-- badge fulfillments update
-
-.. note::
-    Events async processing happens in a separate specific (out of the standard Django request-response flow) worker process.
-    See EventBus documentation for details.
 
 Events subscription
 -------------------
 
-`Feature configuration`_ provides an exclusive list of processed events.
-`Badge Processor`_ is auto-connected to listen to those event types.
+    Only explicitly configured `event types`_ take part in the processing.
+
+See Badges `default settings`_ for the default set of supported events.
+Though, it is expected that any public signal from the `openedx-events`_ library can extend this set with a single requirement: its payload includes a learner PII (UserData object).
+
+
+Learner identification
+----------------------
+
+    Each incoming event must be associated with a specific learner.
 
-All registered events are expected to carry user data. In addition, different event types include their specific data set which can be used for `badge requirements`_ specification.
+The system tries to identify a learner by the `UserData` object in the event payload.
+If the learner is not found, the event is ignored.
+
+The system also ensures that such learner exists in the Credentials (creates if needed).
 
-    External async events are retranslated as internal Credentials (standard Django) signals, so registered receivers can process it.
 
 Requirements analysis
 ---------------------
 
-Once `Event` received, `Badge Processor`_ runs its processing pipeline.
-As a result a relevant requirements set for a specific event type is formed.
+Since any requirement is associated with a single event type, all relevant requirements are collected for the incoming signal:
 
-Fulfillments update
----------------------
+- appropriate event type;
+- active badge templates;
+
+Each requirement's rules are checked against the event payload.
+Requirement processing is dropped as soon as the system recognizes not applying rules.
+
+
+Progress update
+---------------
+
+Current learners' badge progress is stored in the ``Badge Progress`` record.
+
+    Since badge templates can have more than one requirement, the system should track intermediate progresses as well.
+
+Once all rules of the processed requirement apply, the system:
+
+- ensures there is the badge progress record for the learner;
+- marks the requirement as fulfilled for the learner;
+
+If a Badge Progress is recognized as completed (all requirements for the badge template are fulfilled), the system initiates the awarding process.
+
+
+Badge awarding
+--------------
+
+    Once all requirements for the badge template are fulfilled, the system should award the badge.
+
+On badge progress completion, the system:
+
+- creates an *internal* user credential record for the learner;
+- notifies (public signal) about new badge awarded;
+- tries to issue an *external* Credly badge for the learner;
+
+.. note::
 
-Once event-related requirements set is clear, Processor updates/creates corresponding `Fulfillments`_'s attributes for the event-learner.
+    The Badges application implements its extended ``UserCredential`` version (the CredlyBadge) to track external issuing state. Once the Credly badge is successfully issued the **CredlyBadge is updated with its UUID and state**.
 
-.. _public events: https://github.com/openedx/openedx-events/blob/main/openedx_events/tooling.py
-.. _Feature configuration: configuration.html#feature-configuration
-.. _badge requirements: configuration.html#requirements-setup
-.. _Badge Processor: details.html#badge-processor
-.. _Fulfillments: details.html#fulfillment
+.. _event types: https://docs.openedx.org/projects/openedx-events/en/latest/
+.. _openedx-events: https://github.com/openedx/openedx-events
+.. _default settings: settings.html#default-settings