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/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" {
+            edxPlatform = container "openedx-platform" "LMS and course management" "Python/Django"
+            eventBus = container "Event Bus" "Redis Streams or Kafka" "" "Queue"
+            credentialsService = container "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 -> edxPlatform "Completes courses and assignments"
+        learner -> vcIssuerMFE "Requests verifiable credential"
+
+        # --- Event Bus flows ---
+
+        # LMS produces events consumed by Credentials
+        edxPlatform -> 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 "#08427b"
+                fontSize 22
+                shape Person
+            }
+            element "Software System" {
+                background "#1168bd"
+                color "#ffffff"
+            }
+            element "Existing System" {
+                background "#999999"
+                color "#ffffff"
+            }
+            element "Container" {
+                background "#438dd5"
+                color "#ffffff"
+            }
+            element "Component" {
+                background "#85bbf0"
+                color "#000000"
+            }
+            element "Database" {
+                shape Cylinder
+            }
+            element "Queue" {
+                shape Pipe
+            }
+        }
+    }
+      configuration {
+        scope softwaresystem
+    }
+}