ADR 0011: Certificate lifecycle decisions
- Status: accepted, not yet implemented
- Date: 2026-11-07 (all recommendations accepted by the user)
- Decision makers: the user
:::info Planned work, not built
Nothing in this record is built. The system that runs today issues a certificate when an administrator or a role-gated call asks for one. See Certificate verification for what runs. The full specification is in .kiro/specs/certificate-lifecycle/ (requirements REQ-001 to REQ-030, a design, and a design review that requested changes on its last revision).
:::
Context and problem statement
A certificate used to be a row created by hand. The user asked for a proper certificate management solution at administrator level, where certificates are issued automatically when candidates complete the requirements, and a certificate has a lifecycle. Several product choices had to be made before design.
Decision drivers
- Automatic issue where the risk is low, a person in the loop where it matters.
- A certificate that anyone can check, and that can be revoked.
- No surprise mass issue on the day it goes live.
Considered options
Each decision A to K had options with a recommendation. The user accepted every recommendation.
Decision outcome
| Decision | Accepted option |
|---|---|
| A. Issue timing | Per course or programme setting. Auto-issue by default for course certificates, review first for programme and graduation certificates. |
| B. Criteria | Course: mandatory lessons, all quizzes at their own pass mark, all assignments at their own pass mark, attendance (default 80%). Each can be switched off per course. Programme: required courses, TRL and milestones, graduation sign-off, optional cutoff date. Administrators see the effect of stricter rules before they apply. |
| C. Types in the first release | Course completion and programme or graduation. Participation and mentor recognition later. |
| D. Expiry | No expiry by default, optional per template. The valid_until field and expired state are in the first release. Renewal is later. |
| E. Tamper evidence | A verification key plus a stored record fingerprint in the first release. Digitally signed PDFs later, once RTIH decides who holds the signing certificate. The public verify page shows the full name. |
| F. Numbering | Keep RTIH-<year>-<5 digits>, one global sequence. A reissue keeps the number and adds a version. |
| G. Revoke and reissue | The Administrator decides. A Spoke Coordinator can request it with a reason. |
| H. Mentor visibility | Read-only, assigned mentees only. |
| I. LinkedIn and Open Badges | Later. |
| J. Existing certificates | Keep all as issued, version 1. Confirmed test certificates are revoked with the reason "test data", never deleted. |
| K. Go-live backlog | The first run is a dry run. An Administrator bulk-approves, then auto-issue switches on. |
The design builds on these and adds seven of its own, including: stay in the LMS service, split "where a founder stands" from "the certificate", evaluate from a transactional work queue with a daily sweep, let the database be the referee, and keep one state machine in one class.
Consequences
- Good: the choices are fixed before build, so tasks can be sized.
- Bad: until built, none of the lifecycle exists. Certificates are not issued automatically.
- Bad: the design review requested changes, so the design text may still move.
Confirmation
Not applicable yet. When built, the state machine, the queue and the audit rows are the checkable parts.
Sources
.kiro/specs/certificate-lifecycle/requirements.md (decision table), .kiro/specs/certificate-lifecycle/design.md, .kiro/specs/certificate-lifecycle/design-review.md.