Skip to content

Commit 601a58a

Browse files
GlugovGrGlibGlugovGrGlib
authored
Improve badges and verifiable credentials documentation (#2968)
* docs: update readme and fix typos in credentials sharing docs * docs(vc): move credentials sharing docs under the same parent dir * docs: major docs refresh and improvement * docs: finalize c4 diagrams and text enhancements * docs: major update and docs polishing for credentials sharing * docs: update diagrams and screenshots for badges and credentials sharing Add new badge admin screenshots (Accredible API config, activation, Credly organization) and processing flow diagram. Update C4 architecture diagrams and optimize existing image assets. * docs: improve badges documentation with provider configs and quickstart Enhance badge provider configuration docs for Accredible and Credly. Rewrite quickstart guide with prerequisites and step-by-step flow. Update configuration index, management, processing, examples, and settings pages for accuracy and clarity. * docs: revise verifiable credentials documentation and add managing guide Rewrite components, quickstart, and configuration pages for clarity. Add new managing guide for credential lifecycle operations. Update overview, storages, extensibility, composition, tech details, and API reference sections. * docs: update sharing section index with revised structure * docs: enhance host in template urls wording * docs: correct wording based on the feedback after refactoring * docs: small sentance adjustment * docs: additional corrections and elaboration * docs: fix broken link
1 parent b9c9da1 commit 601a58a

51 files changed

Lines changed: 3141 additions & 2010 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎README.rst‎

Lines changed: 28 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,38 @@
1-
edX Credentials Service |Codecov|_
2-
====================================
1+
============================
2+
Open edX Credentials Service
3+
============================
34

4-
.. |Codecov| image:: http://codecov.io/github/edx/credentials/coverage.svg?branch=master
5-
.. _Codecov: http://codecov.io/github/edx/credentials?branch=master
5+
| |status-badge| |license-badge| |CI| |Codecov|
66
7-
This repository contains the edX Credentials Service, which supports course and program certificates. This service is a
8-
replacement for the ``certificates`` app in ``edx-platform``.
7+
.. |CI| image:: https://github.com/openedx/credentials/actions/workflows/ci.yml/badge.svg
8+
:target: https://github.com/openedx/credentials/actions?query=workflow%3ACI
9+
:alt: Test suite status
910

10-
Credentials can be run as part of devstack_ or Tutor_ (using the tutor_credentials_ plugin).
11+
.. |Codecov| image:: https://codecov.io/github/openedx/credentials/coverage.svg?branch=master
12+
:target: https://codecov.io/github/openedx/credentials?branch=master
13+
:alt: Code coverage
1114

12-
.. _devstack: https://github.com/openedx/devstack
15+
.. |status-badge| image:: https://img.shields.io/badge/Status-Maintained-brightgreen
16+
:alt: Maintained
17+
18+
.. |license-badge| image:: https://img.shields.io/github/license/openedx/credentials.svg
19+
:target: https://github.com/openedx/credentials/blob/master/LICENSE
20+
:alt: License
21+
22+
Purpose
23+
=======
24+
25+
This repository contains the Open edX Credentials Service, which supports course and program certificates.
26+
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.
27+
28+
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.
29+
30+
.. _openedx-platform: https://github.com/openedx/openedx-platform/tree/master
1331
.. _tutor: https://docs.tutor.edly.io/
1432
.. _tutor_credentials: https://github.com/overhangio/tutor-credentials
1533

1634
Where to run `make` commands
17-
--------------------------
35+
----------------------------
1836

1937
Due to the nature of developing in containers, some commands must be ran inside the container. Currently most commands
2038
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_.
102120

103121
.. _`discussion forums`: https://discuss.openedx.org
104122
.. _Slack: http://openedx.slack.com/
123+

‎docs/_diagrams/sharing/badges_processing.mmd‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
flowchart TD
2+
A[Incoming event] --> B{Event type configured for badges?}
3+
B -- No --> Z1[Ignore event]
4+
B -- Yes --> C{UserData present?}
5+
C -- No --> Z2[Drop event]
6+
C -- Yes --> D[Find or create learner in Credentials]
7+
8+
D --> E[Find active badge requirements for this event type]
9+
E --> F{Requirement rules match event payload?}
10+
F -- No --> Z3[Skip requirement]
11+
F -- Yes --> G[Create or update Badge Progress]
12+
G --> H[Mark requirement fulfilled]
13+
14+
H --> I{Are all requirements fulfilled?}
15+
I -- No --> Z4[Wait for more matching events]
16+
I -- Yes --> J[Create internal badge record]
17+
J --> K[Emit badge awarded signal]
18+
K --> L[Issue badge through provider API]
19+
L --> M[Update external badge identifier and state]
20+
21+
D --> P[Find active penalties for this event type]
22+
P --> Q{Penalty rules match event payload?}
23+
Q -- No --> Z5[No penalty action]
24+
Q -- Yes --> R[Reset linked requirement progress]
25+
R --> S[Update internal badge state]
26+
S --> T[Update provider badge state]
27+
T --> U[Credly: revoked<br/>Accredible: expired]

‎docs/_diagrams/sharing/credential_sharing.dsl‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
/*
2+
* C4 model for the Credential Sharing feature in Open edX.
3+
* Covers Digital Badges and Verifiable Credentials.
4+
*
5+
* Written in Structurizr DSL (https://structurizr.org/).
6+
*/
7+
workspace "Credential Sharing" {
8+
9+
model {
10+
siteAdmin = person "Site Admin" "Configures badge templates and VC issuing"
11+
learner = person "Learner" "Earns credentials through learning activities"
12+
verifier = person "Verifier" "Employer or institution that verifies learner credentials"
13+
14+
digitalWallet = softwareSystem "Digital Wallet" "Learner Credential Wallet or compatible storage"
15+
digitalBadgePlatform = softwareSystem "Digital Badge Platform" "Credly, Accredible" "Existing System"
16+
17+
openedX = softwareSystem "Open edX" {
18+
openedxPlatform = container "Open edX Platform" "LMS and course management" "Python/Django"
19+
eventBus = container "Event Bus" "Redis Streams or Kafka" "" "Queue"
20+
credentialsService = container "Open edX Credentials" "Stores learner achievements, issues credentials" "Python/Django" {
21+
credentialsCore = component "Credentials Core" "Manages course and program certificates" "Django"
22+
digitalBadgesIssuer = component "Digital Badges Issuer" "Processes badge requirements, issues badges to external platforms" "Django"
23+
verifiableCredentialsIssuer = component "Verifiable Credentials Issuer" "Issues W3C Verifiable Credentials, signs with didkit (Ed25519)" "Django"
24+
vcIssuerMFE = component "Learner Record MFE" "UI for learners to request verifiable credentials" "React"
25+
}
26+
credentialsDB = container "MySQL" "Credentials database" "" "Database"
27+
}
28+
29+
# --- Actors ---
30+
31+
siteAdmin -> credentialsCore "Configures badge templates and VC settings" "Admin panel"
32+
learner -> openedxPlatform "Completes courses and assignments"
33+
learner -> vcIssuerMFE "Requests verifiable credential"
34+
35+
# --- Event Bus flows ---
36+
37+
# LMS produces events consumed by Credentials
38+
openedxPlatform -> eventBus "Publishes certificate and course passing status events" "openedx-events"
39+
eventBus -> credentialsCore "Delivers certificate and course grades events" "openedx-events"
40+
eventBus -> digitalBadgesIssuer "Delivers badge-related events" "learning-badges-lifecycle topic"
41+
42+
# Credentials produces events back to the bus
43+
digitalBadgesIssuer -> eventBus "Publishes badges lifecycle events" "openedx-events"
44+
45+
# --- Internal flows ---
46+
47+
credentialsCore -> credentialsDB "Uses" "Django ORM"
48+
digitalBadgesIssuer -> credentialsDB "Uses" "Django ORM"
49+
verifiableCredentialsIssuer -> credentialsDB "Uses" "Django ORM"
50+
51+
# --- External integrations ---
52+
53+
# Badges
54+
digitalBadgesIssuer -> digitalBadgePlatform "Issues and revokes badges" "REST API"
55+
56+
# Verifiable Credentials
57+
vcIssuerMFE -> verifiableCredentialsIssuer "Initiates VC issuance"
58+
verifiableCredentialsIssuer -> digitalWallet "Sends signed verifiable credential"
59+
digitalWallet -> verifiableCredentialsIssuer "Sends issuance request" "HTTP"
60+
61+
# Verification
62+
verifier -> verifiableCredentialsIssuer "Checks credential revocation status" "StatusList2021 API"
63+
verifier -> digitalBadgePlatform "Checks badge revocation status" ""
64+
65+
}
66+
67+
views {
68+
systemContext openedX "SystemContext" "High-level view of Credential Sharing" {
69+
include *
70+
autoLayout lr
71+
}
72+
73+
container openedX "Containers" "Open edX containers involved in credential sharing" {
74+
include *
75+
autoLayout lr
76+
}
77+
78+
component credentialsService "Components" "Credentials service internal components" {
79+
include *
80+
autoLayout lr
81+
}
82+
83+
styles {
84+
element "Person" {
85+
color "#ffffff"
86+
background "#0b3d91"
87+
fontSize 22
88+
shape Person
89+
}
90+
element "Software System" {
91+
background "#005a9c"
92+
color "#ffffff"
93+
}
94+
element "Existing System" {
95+
background "#4a4a4a"
96+
color "#ffffff"
97+
}
98+
element "Container" {
99+
background "#2b7bbb"
100+
color "#ffffff"
101+
}
102+
element "Component" {
103+
background "#dbeafe"
104+
color "#111111"
105+
}
106+
element "Database" {
107+
shape Cylinder
108+
}
109+
element "Queue" {
110+
shape Pipe
111+
}
112+
}
113+
}
114+
configuration {
115+
scope softwaresystem
116+
}
117+
}

‎docs/_static/images/badges/badges-admin-accredible-api-config.png‎

50.4 KB
Loading

‎docs/_static/images/badges/badges-admin-activation.png‎

28.4 KB
Loading

‎docs/_static/images/badges/badges-admin-credly-organization.png‎

60 KB
Loading

‎docs/_static/images/badges/badges-admin-template-details.png‎

-41.3 KB
Loading

‎docs/_static/images/badges/badges-processing-flow.png‎

93.3 KB
Loading

‎docs/_static/images/sharing/credential_sharing_components.png‎

617 KB
Loading

‎docs/_static/images/sharing/credential_sharing_containers.png‎

452 KB
Loading

0 commit comments

Comments
 (0)