Concepts
########

This section explains the key concepts behind the learning-credentials service.

Credential Lifecycle
********************

A credential goes through the following statuses during its lifecycle:

1. **GENERATING** — The credential generation task has started (e.g., the PDF is being created and uploaded).
2. **AVAILABLE** — The credential has been successfully generated and is available for download.
3. **ERROR** — The generation process failed. The credential can be regenerated by running the generation task again.
4. **INVALIDATED** — The credential has been invalidated (e.g., due to a name change or reissue). The PDF is archived and made inaccessible.

.. graphviz::

    digraph lifecycle {
        rankdir=LR
        node [shape=box, style=filled, fillcolor=gray95]

        GENERATING -> AVAILABLE [label="success"]
        GENERATING -> ERROR [label="failure"]
        ERROR -> GENERATING [label="retry"]
        AVAILABLE -> INVALIDATED [label="invalidate\nor reissue"]
    }

Credential Types and Configurations
************************************

The system separates **what** a credential is from **where** it applies:

- **CredentialType**: A reusable definition specifying the retrieval function (who is eligible), the generation function (how to create the credential), and default custom options. For example, "Certificate of Completion" or "Certificate of Achievement".

- **CredentialConfiguration**: Links a credential type to a specific learning context (course or Learning Path). It can override the default custom options from the type and define a schedule for automatic generation.

This separation allows a single credential type to be reused across many courses while allowing per-course customization.

Retrieval and Generation Functions
**********************************

Credential processing is split into two pluggable steps:

- **Retrieval functions** (prefixed with ``retrieve_``) determine which users are eligible for a credential. They check criteria such as grades, completion percentages, or a combination of both.

- **Generation functions** (prefixed with ``generate_``) create the actual credential artifact (e.g., a PDF). They receive eligible user data and produce a downloadable credential.

Both function types are auto-discovered via reflection and can be extended by adding new functions to the respective modules.

Verification
************

Each credential has two UUIDs:

- **uuid** (primary key): Used internally to identify the credential. Not exposed publicly.
- **verify_uuid**: A separate UUID used for third-party verification. This UUID can be embedded on the PDF (via the ``{verify_uuid}`` placeholder) and used with the public metadata API to verify a credential's authenticity and status.

The public verification API endpoint (``/api/learning_credentials/v1/metadata/<verify_uuid>/``) returns the credential's metadata including the holder's name, issue date, learning context, status, and any invalidation reason. This allows employers or other third parties to verify credentials without authentication.