Lifecycles
This page shows the states of the records that drive the product and what moves each one. The states are the values the database accepts for the status column of each table (a CHECK constraint), and the transitions are the ones the code performs. Each section names the service that owns the transitions: no other code changes that status.
The tables are described in Domain model. The same states, as a user sees them on screen, are in Record states.
Application
Section titled “Application”Table applications, column status. An application is created by the lead intake (apps/api/src/modules/recruit/lead-intake/lead-intake.service.ts). After that, only the move service changes its stage or status (apps/api/src/modules/recruit/funnel/application-move.service.ts).
stateDiagram-v2
[*] --> active: Lead arrives
[*] --> not_qualified: Knockout answer
active --> active: Move stage
active --> hired: Hire
hired --> active: Undo hire
active --> not_qualified: Mark not qualified
active --> withdrawn: Mark withdrawn
active --> closed: System closes
state "Out of the pipeline" as out {
not_qualified
withdrawn
closed
}
out --> active: Reopen
| Transition | Who triggers it | Notes |
|---|---|---|
Created as active |
A lead from the careers form, the lead API, an import, a referral link or a recruiter | Placed in an open stage of the pipeline. Emits application.created. |
Created as not_qualified |
The lead intake, when an answer fails a knockout rule | Placed in the system stage “Not qualified” with the reason knockout. A job can instead send knockouts to review, and then the application is created active. |
active to active |
A recruiter with recruit.applications.move, or an automation action |
The stage changes, the status does not. Emits application.stage_changed. |
active to not_qualified |
A recruiter, with a reason | Moves to the system stage “Not qualified”. Emits application.rejected. |
active to withdrawn |
A recruiter, with a reason | Keeps its stage, for conversion analysis. Emits application.withdrawn. |
active to closed |
The system only | Reason merged when two candidates are merged, or hired_elsewhere when the candidate is hired through another application. Keeps its stage. Emits no event. |
active to hired |
The Hire action only (recruit.applications.hire and people.directory.manage) |
Moves to the Hired stage and creates or links the person. Emits application.hired. |
not_qualified, withdrawn or closed to active |
A recruiter (“Reopen”), or a new lead whose answers now pass the knockout rules | Refused when the candidate has another active application for the same job. Emits application.reopened. |
hired to active |
“Undo hire” only, up to 7 days after the hire | The person created by the hire is archived. Emits application.reopened. |
An arrow that leaves the box “Out of the pipeline” applies to the three states inside it.
The status and the kind of the stage always agree: active only in an open stage, hired only in the Hired stage, not_qualified only in the system stage. withdrawn and closed keep the stage the application was in.
Full application
Section titled “Full application”Table driver_applications, column status. This is the complete employment application the candidate fills in and signs on a public link. The transitions are in apps/api/src/modules/recruit/full-application.
stateDiagram-v2 [*] --> sent: Send full application sent --> in_progress: First answer saved in_progress --> signed: Candidate signs signed --> changes_requested: Request changes changes_requested --> signed: Candidate signs again
| Transition | Who triggers it | Notes |
|---|---|---|
Created as sent |
A recruiter (“Send full application”) or the automation action send_full_application |
One per application of the pipeline. Emits full_application.sent on the first link. |
sent to in_progress |
The candidate, on the public page | On the first step saved, document uploaded or consent accepted. |
in_progress to signed |
The candidate, by signing | Happens in the transaction that completes the signing envelope. The application becomes read only. Emits full_application.signed. |
signed to changes_requested |
A recruiter (“Request changes”), with a note | The earlier signature is kept and marked as superseded. A new signature is required. |
changes_requested to signed |
The candidate, by signing again | A new envelope and a new signed PDF. |
“Resend” and “Cancel link” replace or disable the link and do not change the status. The constraint also accepts canceled, but no code path writes it.
Table offers, column status. The transitions are in apps/api/src/modules/recruit/offers. An offer is signed through a signing envelope, and the end of the envelope is what closes the offer.
stateDiagram-v2 [*] --> sent: Send offer sent --> accepted: Candidate signs sent --> declined: Candidate declines sent --> expired: Limit date passes sent --> withdrawn: Withdraw accepted --> [*] declined --> [*] expired --> [*] withdrawn --> [*]
| Transition | Who triggers it | Notes |
|---|---|---|
Created as sent |
A recruiter with recruit.offers.manage (“Send offer”) |
The row is inserted as draft and becomes sent in the same transaction, once its envelope exists. An application has at most one open offer. |
sent to accepted |
The candidate, by signing the offer | The envelope reaches completed. Emits offer.accepted. |
sent to declined |
The candidate, on the signing page | The reason typed is copied to the offer. Emits offer.declined. |
sent to expired |
The worker, once a minute | The envelope passed its limit date. Emits offer.expired. |
sent to withdrawn |
A recruiter (“Withdraw”) | Cancels the envelope. Refused when the candidate has just answered. |
The constraint also accepts viewed, but the row never takes it. When the candidate opens the document, offers.viewed_at is written and the screen reads “Viewed” from the signer of the envelope.
Signing envelope
Section titled “Signing envelope”Table signing_envelopes, column status. Every signed document uses the signing service (apps/api/src/modules/platform-signing/signing.service.ts): offers, full applications, contracts and policies, road test certificates and the answers of previous employers. The module that owns the document creates the envelope and reacts to its end.
stateDiagram-v2
[*] --> draft: Module creates it
draft --> sent: Worker stores the PDF
state "Open for signature" as open {
sent --> partially_signed: A signer signs
}
open --> completed: Last signer signs
open --> declined: A signer declines
open --> expired: Limit date passes
open --> canceled: Module cancels
draft --> canceled: Module cancels
| Transition | Who triggers it | Notes |
|---|---|---|
Created as draft |
The module that owns the document | The content is frozen, with its variables replaced, and a job is queued for the PDF. |
draft to sent |
The worker (queue platform-signing, job render-document) |
The PDF is stored and its SHA-256 hash recorded. Each signer who signs by link and has an email address gets the signing request. |
sent to partially_signed |
A signer | Signers sign in the order given. The database refuses a signature out of order, on an expired or closed envelope, or over a different document hash. |
sent or partially_signed to completed |
The last signer | The worker then stores the final PDF, with the proof pages (job store-final-pdf). Emits signing.completed. |
sent or partially_signed to declined |
A signer, on the signing page | Emits signing.declined. |
sent or partially_signed to expired |
The worker, once a minute | Emits signing.expired. |
draft, sent or partially_signed to canceled |
The module that owns the document | For example “Withdraw” on an offer, or a document replaced before it was signed. |
An arrow that leaves the box “Open for signature” applies to both states inside it. A completed envelope never changes status. When a signed full application is reopened with “Request changes”, the envelope stays completed and gets a superseded entry in its audit trail (signing_events).
Each signer has its own status in signing_signers: pending, viewed when the document is first opened, then signed or declined.
Driver file and eligibility
Section titled “Driver file and eligibility”Table driver_files. A driver file has three stored facts, all written by the compliance engine (apps/api/src/modules/compliance/engine) and by nothing else:
phase: where the driver is in the relationship with the company.status:compliant,pendingorexpired, a summary of its items.eligible: whether the driver may be dispatched, with the reasons inineligible_reasonswhen not.
stateDiagram-v2 [*] --> hiring: Opened for an application [*] --> active: Opened for a person hiring --> active: Hire active --> hiring: Undo hire active --> terminated: Termination terminated --> active: Termination undone
| Transition | Who triggers it | Notes |
|---|---|---|
Created as hiring |
“Start pre-hire screening”, the candidate signing the full application, or the Hire action when neither happened before | The file belongs to the application and gets the required items of its driver type. |
Created as active |
A driver registered directly in People > Directory | The file belongs to the person. |
hiring to active |
The Hire action | The same row moves from the application to the person. Items, documents and history go with it; nothing is copied. |
active to hiring |
“Undo hire” | The file goes back to the application. |
active to terminated |
People, when the status of the person becomes terminated |
The file is recalculated one last time, becomes read only and gets the end date of its retention. |
terminated to active |
People, when the termination is undone | The file is writable again. |
Eligibility
Section titled “Eligibility”stateDiagram-v2 [*] --> not_eligible: Opened, an item blocks [*] --> eligible: Opened, nothing blocks not_eligible --> eligible: Nothing blocks any more eligible --> not_eligible: Item blocks, hold or termination
The engine recalculates a driver file inside every transaction that changes one of its items, and once a day for dates: a pass of the worker runs every hour and takes the driver files not yet recalculated since the start of the day of their company. After each recalculation, eligible is true only when all three hold:
- No required item is blocking. A required item blocks when it is
expired; when it ismissingorrejectedand has no due date or is past it; when a document was sent, was never reviewed and the due date has passed; or when a new document was sent over an approved one whose validity has already passed. compliance_holdis off. The hold is turned on by a database trigger of the drug and alcohol vault: a pre-employment test that is positive or refused, a full Clearinghouse query that returns “prohibited”, or a record marked “Not cleared”. The engine reads only the flag, never a result. See Sensitive data.- The phase is not
terminated.
A change of eligible emits compliance.eligibility_changed, and a change of status emits compliance.status_changed. The stored status is expired when any item is expired, otherwise pending when any item is missing, sent, rejected or expiring, otherwise compliant.
Compliance item
Section titled “Compliance item”Table compliance_items, column status. The diagram shows the usual path of a document; the table below it is complete.
stateDiagram-v2 [*] --> missing: Engine creates the item missing --> submitted: Document sent submitted --> valid: Approve submitted --> rejected: Reject rejected --> submitted: Document sent again valid --> expiring: Validity is near expiring --> expired: Validity passed expiring --> submitted: New document sent expired --> submitted: New document sent
| Operation | Allowed from | Result | Who |
|---|---|---|---|
| Submit a document | missing, rejected |
submitted |
The driver or candidate (public link), or a user |
| Replace the document | submitted, valid, expiring, expired |
submitted |
The driver, or a user |
| Approve | missing, submitted, valid, expiring, expired |
valid |
A user, or the system when a screening is reviewed or an envelope is completed |
| Reject, with a reason | missing, submitted |
rejected |
A user |
| Waive, with a reason | missing, submitted, valid, expiring, expired, rejected |
waived |
A user |
| Reopen | submitted, valid, expiring, expired, rejected, waived |
missing |
A user |
| Date passes | valid |
expiring, when the validity is within the company setting (30 days by default) |
The engine, once a day |
| Date passes | expiring |
expired, the day after the validity |
The engine, once a day |
| Rule stops applying | Any | not_applicable |
The engine. The item returns to its earlier status if the rule applies again. |
A periodic item of a driver already hired is created as valid, with its first cycle counted from the hire date. Items of the drug and alcohol file are never reviewed by these operations: they are valid while the vault answers that a record that fulfills the rule is on file.
Safety history request
Section titled “Safety history request”Table safety_history_requests, column status. One request per previous employer, under 49 CFR 391.23. The transitions are in apps/api/src/modules/compliance/safety-history.
stateDiagram-v2
[*] --> sent: Request safety history
state "Waiting for the employer" as waiting {
sent --> reminded: Reminder
reminded --> reminded: Next reminder
sent --> no_response: 30 days pass
reminded --> no_response: 30 days pass
}
waiting --> answered: Employer answers
waiting --> no_record: Employer has no record
waiting --> canceled: Cancel
The three states in the box are the ones in which the request still waits for the employer. An arrow that leaves the box applies to all three.
| Transition | Who triggers it | Notes |
|---|---|---|
Created as sent |
A user with compliance.screenings.manage (“Request safety history”) |
Requires the authorization the candidate signed in the full application. The email to the employer and the first attempt are written in the same transaction. |
sent to reminded |
The worker, every 10 minutes | Reminder emails 7, 14 and 21 days after the request, each recorded as an attempt. |
sent or reminded to no_response |
The worker, every 10 minutes | The day after the 30-day deadline. With two attempts recorded, the item of the driver file is met as “No response documented”. |
sent, reminded or no_response to answered or no_record |
The previous employer, on the public page | The answer is signed through a signing envelope. Drug and alcohol answers go straight to the vault. |
sent, reminded or no_response to canceled |
A user (“Cancel”) | The link stops working. |
Logging an attempt by hand (“Log attempt”: a call, a fax, a letter) adds a row to safety_history_attempts and does not change the status.