docs(sharing): badges and verifiable credentials documentation rework

README.rst

@@ -1,20 +1,38 @@
-edX Credentials Service |Codecov|_
-====================================
+============================
+Open edX Credentials Service
+============================
 
-.. |Codecov| image:: http://codecov.io/github/edx/credentials/coverage.svg?branch=master
-.. _Codecov: http://codecov.io/github/edx/credentials?branch=master
+| |status-badge| |license-badge| |CI| |Codecov|
 
-This repository contains the edX Credentials Service, which supports course and program certificates. This service is a
-replacement for the ``certificates`` app in ``edx-platform``.
+.. |CI| image:: https://github.com/openedx/credentials/actions/workflows/ci.yml/badge.svg
+    :target: https://github.com/openedx/credentials/actions?query=workflow%3ACI
+    :alt: Test suite status
 
-Credentials can be run as part of devstack_ or Tutor_ (using the tutor_credentials_ plugin).
+.. |Codecov| image:: https://codecov.io/github/openedx/credentials/coverage.svg?branch=master
+    :target: https://codecov.io/github/openedx/credentials?branch=master
+    :alt: Code coverage
 
-.. _devstack: https://github.com/openedx/devstack
+.. |status-badge| image:: https://img.shields.io/badge/Status-Maintained-brightgreen
+    :alt: Maintained
+
+.. |license-badge| image:: https://img.shields.io/github/license/openedx/credentials.svg
+    :target: https://github.com/openedx/credentials/blob/master/LICENSE
+    :alt: License
+
+Purpose
+=======
+
+This repository contains the Open edX Credentials Service, which supports course and program certificates.
+This service is an extension to `openedx-platform`_ providing a set of unique features in the credentials domain such as Badges, Verifiable Credentials, Learning Records, and Program Certificates.
+
+The easiest way to run Credentials service is by using Tutor_, the community-supported, Docker-based Open edX distribution, by installing the tutor_credentials_ plugin.
+
+.. _openedx-platform: https://github.com/openedx/openedx-platform/tree/master
 .. _tutor: https://docs.tutor.edly.io/
 .. _tutor_credentials: https://github.com/overhangio/tutor-credentials
 
 Where to run `make` commands
---------------------------
+----------------------------
 
 Due to the nature of developing in containers, some commands must be ran inside the container. Currently most commands
 can be ran either inside the container or inside a local virtual environement, once developer requirements have been
@@ -102,3 +120,4 @@ Our real-time conversations are on Slack_.
 
 .. _`discussion forums`: https://discuss.openedx.org
 .. _Slack: http://openedx.slack.com/
+

docs/_diagrams/sharing/badges_processing.mmd

@@ -0,0 +1,27 @@
+flowchart TD
+    A[Incoming event] --> B{Event type configured for badges?}
+    B -- No --> Z1[Ignore event]
+    B -- Yes --> C{UserData present?}
+    C -- No --> Z2[Drop event]
+    C -- Yes --> D[Find or create learner in Credentials]
+
+    D --> E[Find active badge requirements for this event type]
+    E --> F{Requirement rules match event payload?}
+    F -- No --> Z3[Skip requirement]
+    F -- Yes --> G[Create or update Badge Progress]
+    G --> H[Mark requirement fulfilled]
+
+    H --> I{Are all requirements fulfilled?}
+    I -- No --> Z4[Wait for more matching events]
+    I -- Yes --> J[Create internal badge record]
+    J --> K[Emit badge awarded signal]
+    K --> L[Issue badge through provider API]
+    L --> M[Update external badge identifier and state]
+
+    D --> P[Find active penalties for this event type]
+    P --> Q{Penalty rules match event payload?}
+    Q -- No --> Z5[No penalty action]
+    Q -- Yes --> R[Reset linked requirement progress]
+    R --> S[Update internal badge state]
+    S --> T[Update provider badge state]
+    T --> U[Credly: revoked<br/>Accredible: expired]

docs/_diagrams/sharing/credential_sharing.dsl

@@ -0,0 +1,117 @@
+/*
+ * C4 model for the Credential Sharing feature in Open edX.
+ * Covers Digital Badges and Verifiable Credentials.
+ *
+ * Written in Structurizr DSL (https://structurizr.org/).
+ */
+workspace "Credential Sharing" {
+
+    model {
+        siteAdmin = person "Site Admin" "Configures badge templates and VC issuing"
+        learner = person "Learner" "Earns credentials through learning activities"
+        verifier = person "Verifier" "Employer or institution that verifies learner credentials"
+
+        digitalWallet = softwareSystem "Digital Wallet" "Learner Credential Wallet or compatible storage"
+        digitalBadgePlatform = softwareSystem "Digital Badge Platform" "Credly, Accredible" "Existing System"
+
+        openedX = softwareSystem "Open edX" {
+            openedxPlatform = container "Open edX Platform" "LMS and course management" "Python/Django"
+            eventBus = container "Event Bus" "Redis Streams or Kafka" "" "Queue"
+            credentialsService = container "Open edX Credentials" "Stores learner achievements, issues credentials" "Python/Django" {
+                credentialsCore = component "Credentials Core" "Manages course and program certificates" "Django"
+                digitalBadgesIssuer = component "Digital Badges Issuer" "Processes badge requirements, issues badges to external platforms" "Django"
+                verifiableCredentialsIssuer = component "Verifiable Credentials Issuer" "Issues W3C Verifiable Credentials, signs with didkit (Ed25519)" "Django"
+                vcIssuerMFE = component "Learner Record MFE" "UI for learners to request verifiable credentials" "React"
+            }
+            credentialsDB = container "MySQL" "Credentials database" "" "Database"
+        }
+
+        # --- Actors ---
+
+        siteAdmin -> credentialsCore "Configures badge templates and VC settings" "Admin panel"
+        learner -> openedxPlatform "Completes courses and assignments"
+        learner -> vcIssuerMFE "Requests verifiable credential"
+
+        # --- Event Bus flows ---
+
+        # LMS produces events consumed by Credentials
+        openedxPlatform -> eventBus "Publishes certificate and course passing status events" "openedx-events"
+        eventBus -> credentialsCore "Delivers certificate and course grades events" "openedx-events"
+        eventBus -> digitalBadgesIssuer "Delivers badge-related events" "learning-badges-lifecycle topic"
+
+        # Credentials produces events back to the bus
+        digitalBadgesIssuer -> eventBus "Publishes badges lifecycle events" "openedx-events"
+
+        # --- Internal flows ---
+
+        credentialsCore -> credentialsDB "Uses" "Django ORM"
+        digitalBadgesIssuer -> credentialsDB "Uses" "Django ORM"
+        verifiableCredentialsIssuer -> credentialsDB "Uses" "Django ORM"
+
+        # --- External integrations ---
+
+        # Badges
+        digitalBadgesIssuer -> digitalBadgePlatform "Issues and revokes badges" "REST API"
+
+        # Verifiable Credentials
+        vcIssuerMFE -> verifiableCredentialsIssuer "Initiates VC issuance"
+        verifiableCredentialsIssuer -> digitalWallet "Sends signed verifiable credential"
+        digitalWallet -> verifiableCredentialsIssuer "Sends issuance request" "HTTP"
+
+        # Verification
+        verifier -> verifiableCredentialsIssuer "Checks credential revocation status" "StatusList2021 API"
+        verifier -> digitalBadgePlatform "Checks badge revocation status" ""
+
+    }
+
+    views {
+        systemContext openedX "SystemContext" "High-level view of Credential Sharing" {
+            include *
+            autoLayout lr
+        }
+
+        container openedX "Containers" "Open edX containers involved in credential sharing" {
+            include *
+            autoLayout lr
+        }
+
+        component credentialsService "Components" "Credentials service internal components" {
+            include *
+            autoLayout lr
+        }
+
+        styles {
+            element "Person" {
+                color "#ffffff"
+                background "#0b3d91"
+                fontSize 22
+                shape Person
+            }
+            element "Software System" {
+                background "#005a9c"
+                color "#ffffff"
+            }
+            element "Existing System" {
+                background "#4a4a4a"
+                color "#ffffff"
+            }
+            element "Container" {
+                background "#2b7bbb"
+                color "#ffffff"
+            }
+            element "Component" {
+                background "#dbeafe"
+                color "#111111"
+            }
+            element "Database" {
+                shape Cylinder
+            }
+            element "Queue" {
+                shape Pipe
+            }
+        }
+    }
+      configuration {
+        scope softwaresystem
+    }
+}