RPL lifecycle

RPL application lifecycle

Audience: all
Status: specced
Owns: product + backend
Depends on: Domain entities, Policies, Workflow abstraction, NSQ lifecycle

An RPL application moves through stages. Within a stage it has a status. Composite examples appear after the tables. Sequencing is also expressed as a seeded RPL workflow_template — see Workflow abstraction.

Stages (ordered)

Code	Label
`DRAFT`	Application drafting
`CENTRE_REVIEW`	Centre review
`PAYMENT`	Payment to centre
`EVIDENCE`	Folder arrangement / evidence collection
`INTERVIEW`	Panel interview
`INTERNAL_VERIFICATION`	Internal verification (IV)
`EXTERNAL_VERIFICATION`	External verification (EV)
`CERTIFICATION`	Certificate issue / collection
`CLOSED`	Terminal

Statuses (reusable)

Code	Meaning
`IN_PROGRESS`	Actor is working
`AWAITING_ACTION`	Waiting on a specific actor
`ATTENTION_REQUIRED`	Feedback; candidate or prior stage must fix
`APPROVED`	Gate passed; advance stage
`REJECTED`	Gate failed
`APPEAL_OPEN`	Appeal / discussion open
`SCHEDULED`	Interview booked
`COMPLETED`	Stage work finished

Close reasons (when stage = `CLOSED`)

Code	Meaning
`CERTIFIED`	Certificate issued / collected path finished
`WITHDRAWN`	Candidate or centre withdrew
`GAP_TRAINING`	Interview unsuccessful; LMS recommendations
`REJECTED_FINAL`	Failed a terminal reject path

Happy path (summary)

DRAFT — Candidate creates an application with sector, trade, centre only; fills the wizard (personal SoT via onboarding, experience/trade preferences, identity verify, declarations) via PATCH; NIN verified + complete draft required before submit; otherwise stuck in draft. Unit ids are preferences only (not assessment scope). At most one DRAFT/IN_PROGRESS app per trade (retry allowed after rejected/withdrawn/certified). Application payload may live in JSONB with schema_version while requirements settle. (Application Form is intended as a real tracked stage once self_service is seeded — see Workflow abstraction.)
CENTRE_REVIEW — Submit → centre reviewer accepts or returns feedback via unified POST /applications/{id}/review with stageKey: application_form (single_approval, engine-backed). Candidate revises and resubmits — application_versions keeps history (v1 on apply, v2 after feedback, …).
PAYMENT — After centre approval, the candidate (or centre staff, for display) may preview the fee with GET /applications/{id}/payment-quote. Only the candidate pays via POST /applications/{id}/pay. CAP computes the fee and initiates processing on Orchestrator; required before Folder Arrangement / facilitator assignment. Only paid applications get a facilitator. On payment.completed, CAP stores a receipt snapshot (paidAt, provider, amounts, candidate) plus receiptAssetId (GET …/receipt returns details even if the PDF URL is still null). The payment row of GET …/stages may include amount + receipt so the centre UI does not need a second quote call. Centre owners list checkouts on GET /centre/payments. See Payment architecture.
EVIDENCE (Folder Arrangement) — Centre assigns a facilitator; candidate fills the Evidence Vault (RPL-only): general uploads, one self-assessment, one third-party report — not NSQ per-unit evidence. Facilitator review / revision via application_versions until approve → interview. Centre may already book an interview sitting here (GET /applications?interviewSchedulable=true; POST /centre/interviews/{id}/schedule or ad-hoc panel/schedule) without entering or completing the interview stage. Evaluate, forms, candidate sign-off, and observer comments stay interview-only.
INTERVIEW — Centre may reuse panel and interview sitting templates (/centre/panels, /centre/interviews; list sittings with from/to/scheduledAt) and copy one onto an application via POST /centre/interviews/{id}/schedule { applicationId } or bulk { items } (frozen per-app snapshot + centreInterviewId; sitting on or after the template clock; not a cohort). Copy/curate/schedule also allowed while still on folder arrangement. Centre diary: GET/PATCH /centre/interview-bookings (application + candidate; PATCH reschedules that application only). Ad-hoc: centre curates a panel of 3 and selects a lead, plus an IV observer who may be one of the three or a fourth person; schedules via POST /applications/{id}/interview/schedule (scheduledAt, mode physical|online, location or useCentreAddress, link when online). GET …/interview/schedule returns the current booking (do not scrape events). useCentreAddress copies GET /centre/profile formatted address (422 if missing). Editing panel members wipes the schedule — POST schedule again. Lead fills the four forms (records, assessment_grid, practical_observation, skill_demonstration) via PUT …/interview/forms/{formType} { data } (blocked after candidate signoff). Candidate signs each form with POST …/forms/{formType}/signoff (signatureMode upload | default | typed). Voting panelists POST …/interview/evaluate (feedback, signatureAssetId); the lead may also send decision approve|reject and, on reject, outcome unsuccessful|inconclusive. Appeal: candidate comment to lead → lead reopens/reschedules or dismisses with reason. Unsuccessful/inconclusive → recommendation service consults LMS (GAP_TRAINING). Success → IV.
INTERNAL_VERIFICATION — Centre assigns an IV (POST /applications/{id}/iv; picker GET /centre/assessors?qualification=IV). GET /applications/{id} includes internalVerifier when assigned. IV reviews all work to date; rejects with comments may return to prior stage (head panelist notified). Success → engine advances to external_verification. Ready-to-share / ready-to-certify queue is GET /applications?ivApproved=true&status=in_progress (IV StageHistory APPROVED — not stage=internal_verification). Centre may POST /applications/{id}/share-token (one live token; POST replaces; DELETE revokes) so a viewer can GET /shared/applications/{token} without Bearer (files via …/assets/{assetId}). Flag-off path: centre forwards to awarding body (POST …/forward-to-awarding-body; IV must be approved). When CAP_CENTRE_CERTIFY_BYPASS is on, PATCH /centre/applications/bulk { ids, action: "certify" } sets CERTIFIED and synthetically closes leftover EV/certification history (no Certificate row / cap.certificate_issued notification). Flag off → 404.
EXTERNAL_VERIFICATION — Awarding body assigns EV per centre (EV must not hold a role at that centre). Issues return to prior stage; clean apps → notify awarding body for certificates.
CERTIFICATION — Awarding body prepares certificate; sends to centre for candidate pickup / digital delivery. Centre-bypass certify (flag on) is the off-platform equivalent of this close-out.

GET /applications/{id}/stages exposes the uniform seven-stage breakdown (Application Form → Payment → Folder Arrangement → Interview → IV → EV → Certification). Calendar: GET /applications/{id}/events (one app), GET /candidate/events (candidate’s apps), and GET /assessor/events (assessor’s actively assigned apps only).

Version history & abstractions

Review and Evidence Vault loops: application_versions + stage-scoped feedback.
Appeals / resolutions: generic across stages — Workflow abstraction.
Actors: evaluators vs evaluatees; handlers single_approval (review, facilitator approve, IV, EV) and panel_evaluation (interview). Planned TODOs: self_service (Application Form), external_gate (Payment).

Example composites

Stage	Status	Meaning
`DRAFT`	`IN_PROGRESS`	Filling form; NIN not verified
`DRAFT`	`AWAITING_ACTION`	NIN verified; can submit
`CENTRE_REVIEW`	`ATTENTION_REQUIRED`	Candidate must amend
`EVIDENCE`	`AWAITING_ACTION`	Awaiting facilitator assignment (payment done)
`INTERVIEW`	`SCHEDULED`	Interview booked
`INTERVIEW`	`APPEAL_OPEN`	Candidate appealed evaluation
`CLOSED`	`COMPLETED` + reason `GAP_TRAINING`	Unsuccessful interview

Concurrent application rule (summary)

A candidate may only have one active (non-draft) application path per policy: after submit, starting another is blocked until feedback/ATTENTION_REQUIRED handling or {x} days without centre response (exact {x} TBD — see Policies).

NSQ

Same early/late stages; after payment see NSQ lifecycle (induction + assessment instead of folder arrangement + interview).