Runtime view
This page follows the six flows that define the product through the running system. Each diagram starts at the HTTP route, and every participant and message is taken from the code: the route, the tables written, the queue, the worker routine and the provider adapter.
What every flow has in common
Section titled “What every flow has in common”The same four mechanisms appear in all the diagrams. They are described once here.
- One transaction per request, with the company in it. A route with a session runs inside one database transaction that carries the company and the user (
app.tenant_idandapp.user_id), and row level security limits every statement to that company. A public route has no session: it finds the company from a public identifier (the slug of the careers page, or the hash of a link token) through agate.public_context_by_*function of the database, and then runs as that company with no user. See Tenant isolation. - The outbox. A business event is a row of
domain_events, written in the same transaction as the change it describes, so the event exists if and only if the change was committed. The worker dispatches the pending events to the consumers registered for each type, at least once, and each consumer is idempotent. - Work is discovered from the database. Most worker routines are a pass repeated on a fixed interval by BullMQ, on Redis. A pass asks the database which companies have work of one kind due (
gate.tenants_with_due_work) and then opens one transaction per company. A committed row is found by the next pass whatever happened to the process that wrote it. See Background work. - One way out for messages. No module calls an SMS or email provider. A module asks the sending service to write a row of
messages; the worker sends it. The last diagram on this page shows that path in full, and the others refer to it as “the sending queue”.
The participants are named the same way in every diagram:
| Participant | What it is |
|---|---|
| Recruiter, Compliance user (web app) | A signed-in user of apps/web, the office system, which calls the API with the generated client. |
| Candidate, Previous employer (careers site) | A visitor of apps/careers, the public site rendered on the server. The browser never calls the API: the site calls it on behalf of the visitor. |
| API | apps/api. |
| PostgreSQL | The database. |
| Worker | apps/worker, which runs the queue consumers and the scheduled routines of every module. Its queues are BullMQ queues on Redis. |
| Object storage | The S3-compatible file store. |
| SMS provider, Email provider | The provider, reached through the adapter selected by configuration: the simulator or Twilio for SMS; the local outbox, SMTP or Amazon SES for email. |
An arrow with an open head from the API to the worker is a job put on a queue. A loop on the worker is a scheduled pass. To keep the diagrams readable, each message is a short label; the numbered notes under each diagram give the route, the tables and the source file.
Lead to first SMS
Section titled “Lead to first SMS”A candidate applies on the careers page and receives the first text message from the system rule “First response”. The rule is created turned off with each company; the flow below is what happens once the company turns it on.
---
config:
sequence:
width: 110
actorMargin: 20
---
sequenceDiagram
actor C as Candidate<br/>(careers site)
participant API
participant DB as PostgreSQL
participant W as Worker
participant SMS as SMS provider
C->>API: POST /public/<br/>applications/<br/>{companySlug}/submit
API->>DB: Company from<br/>the slug
API->>DB: Lead intake writes<br/>candidate, consents,<br/>application, touch
API->>DB: Outbox row<br/>application.created
API-->>C: 202 Accepted
loop Every second
W->>DB: Priority events<br/>pending?
end
W-)W: Queue a delivery<br/>per consumer
W->>DB: Mark the event<br/>dispatched
W->>DB: Automation engine<br/>creates the run
loop Every 10 seconds
W->>DB: Automation<br/>actions due?
end
W->>DB: Sending service<br/>checks and writes<br/>the message
loop Every second
W->>DB: Messages due?
end
W->>DB: Reserve, read<br/>consent again
W->>SMS: Send
SMS-->>W: Message id
W->>DB: Message sent,<br/>response time kept
- The careers site posts the form to
POST /public/applications/{companySlug}/submit(apps/api/src/modules/recruit/public/public-application.service.ts). The company comes from the slug, throughgate.public_context_by_slug. The route answers202in every case, so a visitor cannot tell whether a candidate already existed. - In one transaction, the lead intake (
recruit/lead-intake/lead-intake.service.ts) finds or creates the candidate, creates the application, records the lead touch and the consents, applies the knockout rules, assigns a recruiter and scores the application. It then writes the eventapplication.createdin the outbox. This is the only event type of theprioritylane, which has its own dispatch pass and its own queue, so a new applicant never waits behind a broadcast. An application that comes from a spreadsheet import goes to thedefaultlane instead. - The dispatcher (
core/events/dispatcher.ts) asks the database which companies have a pending event of the lane, reads the events of each company, queues one job per consumer onevents-consume-priorityand marks the events dispatched in the same transaction. - The automation engine (
platform-automations/automation-engine.ts) is one of the consumers. For each enabled rule the event triggers, it creates one row ofautomation_runsand the rows ofautomation_run_actions. An application created as not qualified starts no run. - The actions pass runs the due action. For “First response” that is
recruit/automations/first-response/first-response.automation.ts, which calls the sending service with the idempotency keyfirst_contact:<candidate>:<day>. A second application of the same candidate on the same day sends nothing, and an imported application never gets the message. - The sending service decides whether the message may leave (consent, sender, daily cap, allowed window) and writes it. A first contact has queue priority 0 and, when the company setting “Send the first message at any hour” is on, skips the allowed window.
- The sending pass reserves the message, calls the provider through its adapter and records the result. When the message becomes
sent,applications.first_response_secondsis written.
The waits between the steps are bounded by three polling intervals defined in the code: 1 second for the priority dispatch pass, 10 seconds for the automation actions pass and 1 second for the sending pass.
Complete application with signature
Section titled “Complete application with signature”A recruiter sends the full application, the candidate fills it in on a public link and signs it, and the signed PDF reaches the driver file.
---
config:
sequence:
width: 110
actorMargin: 20
---
sequenceDiagram
actor Rec as Recruiter<br/>(web app)
actor C as Candidate<br/>(careers site)
participant API
participant DB as PostgreSQL
participant W as Worker
Rec->>API: POST /recruit/applications/{id}/<br/>full-application/send
API->>DB: Full application<br/>sent, invite queued
W->>DB: Sending pass makes<br/>the link, keeps<br/>the token hash
W-)C: Invite with the link, by email or SMS
C->>API: GET /public/<br/>full-application/<br/>{companySlug}/<br/>application
API->>DB: Company from<br/>the token hash
loop Each step
C->>API: PUT .../steps/<br/>personal, and the<br/>other steps
API->>DB: Save answers,<br/>in_progress
end
C->>API: POST .../<br/>signature/prepare
API->>DB: Signing envelope<br/>as draft
API-)W: Job render-document
W->>DB: PDF stored,<br/>envelope sent
C->>API: POST .../signature
API->>DB: Signature proof,<br/>envelope completed,<br/>application signed
API->>DB: Driver file opened,<br/>license and medical<br/>card submitted
API-)W: Job store-final-pdf
W->>DB: Final PDF stored,<br/>application item<br/>submitted
W-)C: Signed copy, by email
- “Send full application” is
POST /recruit/applications/{id}/full-application/send(recruit/full-application/full-application.service.ts). It creates the row ofdriver_applicationsand writes one message through the sending service, with a placeholder where the link goes. The token of the link is drawn by the worker at the moment the message leaves, and only its hash is stored. The token is never inmessages.body. - Every public route, under
/public/full-application/{companySlug}/, receives the token in a header (x-full-application-token) and finds the company and the application from its hash, throughgate.public_context_by_full_application_token. A token that is unknown, expired, canceled or of another company gets the same answer. - The steps are saved one at a time (
PUT .../steps/personal,addresses,licenses,employments,history,questionsanddocuments). The Social Security number and the date of birth are encrypted before they are written. See Sensitive data. signature/preparerefuses an incomplete application. Otherwise it asks the signing service to create an envelope with the frozen content of the application. The PDF is made by the worker (queueplatform-signing) and kept in the object storage, so the envelope isdraftfor a moment and thensent.signaturerequires the typed name to match the legal name of step 1 and the IP address of the visitor. The signing service writes the proof insigning_signatures; the database refuses a signature over a different document hash. Completing the envelope tells its listeners in the same transaction:- the full application becomes
signedand read only, and emitsfull_application.signed; - the driver file of the application is opened if it does not exist, and the license and medical card photos become documents “sent, waiting for review” of their items, with the same file and no copy;
- the consent to limited Clearinghouse queries becomes a record of the drug and alcohol file.
- the full application becomes
- The worker builds the final PDF: the pages that were signed, followed by the proof pages. When it is stored, the signed application becomes the document of the item
C18-APPof the driver file, and the candidate gets a copy by email.
Hire to an eligible driver
Section titled “Hire to an eligible driver”The Hire action turns the candidate into a person and moves the driver file to that person. The driver becomes “Eligible” when the compliance engine finds nothing blocking.
---
config:
sequence:
width: 110
actorMargin: 20
---
sequenceDiagram
actor Rec as Recruiter<br/>(web app)
actor Comp as Compliance user<br/>(web app)
participant API
participant DB as PostgreSQL
participant W as Worker
Rec->>API: POST /recruit/applications/{id}/hire
API->>DB: Person created<br/>or linked
API->>DB: Application hired,<br/>other active<br/>ones closed
API->>DB: Driver file moves<br/>to the person,<br/>recalculated
API->>DB: Outbox row<br/>application.hired
API-->>Rec: Application hired, person id
loop Every 2 seconds
W->>DB: Events pending?
end
W->>DB: Onboarding plan<br/>started
loop Each requirement
Comp->>API: POST a screening<br/>review or an<br/>item approval
API->>DB: Item valid, file<br/>recalculated
end
Note over API,DB: Last blocking<br/>item approved
API->>DB: eligible = true
API->>DB: Outbox row<br/>compliance.<br/>eligibility_changed
API-->>Comp: Eligible to drive
POST /recruit/applications/{id}/hireneeds two permissions,recruit.applications.hireandpeople.directory.manage(recruit/hiring/hiring.service.ts). Everything below happens in the transaction of that request; a failure in any step leaves nothing written.- The person is created in
people, or an existing person is linked. The application goes to the Hired stage through the move service, and the other active applications of the candidate are closed with the reasonhired_elsewhere. When the application has a signed full application, its encrypted Social Security number, date of birth and current license number are copied toperson_identityof the person, without being decrypted (see Sensitive data). - The driver file of the application becomes the file of the person in one
UPDATEof one row:person_idis set andphasebecomesactive. Its items, documents and history are not copied. The engine then recalculates: rules that apply only after the hire create their items, and items due “within N days of the hire” get their due date. - The worker dispatches
application.hiredto its consumers.compliance.onboarding-hirestarts the onboarding plan of the person, when the company has an onboarding template that applies.compliance-enginerepeats the driver file step and finds nothing to change. An automation rule triggered by the hire starts here too. - Each review writes one item and recalculates the file in the same transaction. In the reference journey of the product (
e2e/tests/journey.spec.ts) these are the reviews of the motor vehicle record, the PSP report, the medical exam and the road test in Compliance > Screenings, the Clearinghouse query and the pre-employment test recorded in Compliance > Drug and alcohol, and the approval of the license on the driver file. - After each recalculation the engine stores
status,eligibleandineligible_reasonson the driver file. No screen computes eligibility: every screen reads these columns. The rule is in Lifecycles.
Safety history request and employer response
Section titled “Safety history request and employer response”A compliance user asks a previous employer for the safety performance history of a driver (49 CFR 391.23). The employer answers on a public page, with a signature and without an account.
---
config:
sequence:
width: 110
actorMargin: 20
---
sequenceDiagram
actor Comp as Compliance user<br/>(web app)
actor Emp as Previous employer<br/>(careers site)
participant API
participant DB as PostgreSQL
participant W as Worker
Comp->>API: POST /compliance/safety-history/<br/>driver-files/{driverFileId}/requests
API->>DB: Authorization PDF,<br/>request sent,<br/>email queued
W->>DB: Sending pass makes<br/>the link, keeps<br/>the token hash
W-)Emp: Email with the link and the authorization PDF
Emp->>API: GET /public/<br/>safety-history/<br/>request
API->>DB: Company from<br/>the token hash
Emp->>API: POST /public/<br/>safety-history/<br/>respond
API->>DB: Signing envelope<br/>as draft
API-)W: Job render-document
API-->>Emp: submitted: false
W->>DB: PDF stored,<br/>envelope sent
Emp->>API: POST .../respond<br/>again, same body
API->>DB: Drug and alcohol<br/>answers to the vault
API->>DB: Signature, response,<br/>request answered
API->>DB: Driver file<br/>item updated
API-->>Emp: submitted: true
loop Every 10 minutes
W->>DB: Reminders due?<br/>Deadline passed?
end
- A request exists only with the authorization the candidate signed in the full application. For each employer picked, the API renders a PDF with the accepted authorization texts and the proof of that signature, keeps it in the object storage, creates the row of
safety_history_requests, writes the email through the sending service and records the first attempt (compliance/safety-history/safety-history.service.ts). If the email to one employer is refused, nothing is written for any of them. - The link token is drawn when the email leaves, and each new email replaces it, so an employer has one valid link at a time. The authorization PDF is attached by the worker at the same moment; the row of
messageskeeps neither the token nor the file. - The public page runs on the careers site at
/verify/<token>. The API finds the company and the request from the hash of the token, throughgate.public_context_by_safety_history_token. A token that is unknown, expired, replaced, or of a request already answered or canceled gets the same404. - The page calls
respondtwice with the same body. The first call freezes the answers about employment and accidents as the document of a signing envelope and answerssubmitted: false. Once the worker has stored the PDF, the second call signs it. - The second call writes, in one transaction: the drug and alcohol answers, when the request asked for them, straight to the vault; the signature; the row of
safety_history_responses; and the statusanswered, orno_recordwhen the employer has no record of the person. The drug and alcohol answers are never part of the signed document, and no route of this page reads them back. - The engine approves the item of the driver file when every request of the file has an answer, or a documented lack of one.
- Without an answer, the worker sends reminders 7, 14 and 21 days after the request and closes it as
no_responsethe day after the 30-day deadline. A late answer is still accepted.
Audit export
Section titled “Audit export”A compliance user generates the driver files of one or more drivers as PDF, for an audit.
---
config:
sequence:
width: 110
actorMargin: 20
---
sequenceDiagram
actor Comp as Compliance user<br/>(web app)
participant API
participant DB as PostgreSQL
participant W as Worker
participant S3 as Object storage
Comp->>API: POST /compliance/<br/>audit-export/exports
API->>DB: Export queued,<br/>subjects, audit row
API-)W: After commit: job generate
API-->>Comp: Export queued
W->>DB: Export running
loop Each driver file
W->>DB: Read file, items<br/>and history
W->>S3: Read each<br/>document
W->>DB: Log each read,<br/>update progress
end
W->>S3: Store the PDF<br/>or the ZIP
W->>DB: Export completed,<br/>size, hash, expiry
loop Every 2 seconds, while queued or running
Comp->>API: GET /compliance/<br/>audit-export/exports
end
Comp->>API: GET .../exports/<br/>{id}/file
API->>DB: Check status,<br/>expiry, audit row
API->>S3: Read the file
API-->>Comp: File, size and<br/>hash verified
POST /compliance/audit-export/exportsneedscompliance.audit_export.manage(compliance/audit-export/audit-export.service.ts). The scope is one driver, a selection or a filter. The option “Show full identifiers” also needscompliance.sensitive_data.reveal.- The job is queued after the transaction commits (queue
compliance-exports). A pass once a minute also picks up any export stillqueued, so a lost job does not leave an export waiting forever. - The worker builds one PDF per driver file (
audit-export.runner.ts). Every document is read through the file service as the system, and each read leaves a row infile_access_logwith the purposeexport. Identifiers are masked by default. With “Show full identifiers”, each value is revealed as the user who asked, so the permission is checked again at that moment and each reveal is recorded; without the permission the export fails. - Nothing of the drug and alcohol file is in an export. The worker reads as the company with no user, and the policy of that vault returns no row to it.
- One driver file produces a PDF. Several produce a ZIP with one PDF per driver and an
index.csv. The result is stored under the prefix of the company and kept for 7 days. - The download checks that the export is
completedand not expired, writes the audit rowcompliance.audit_export.downloaded, and compares the size and the SHA-256 hash of the stored file with the ones recorded before sending it. - After 7 days the worker deletes the file from the storage and the row stays, as
expired.
Sending a message: the single path
Section titled “Sending a message: the single path”Every outbound SMS and email goes through this path, whoever asks for it: a recruiter typing in the Inbox, an automation, a sequence, a broadcast, a reminder or a system notice. The diagram shows a recruiter sending from the Inbox; the notes below say what changes for automatic messages.
---
config:
sequence:
width: 110
actorMargin: 20
---
sequenceDiagram
actor Rec as Recruiter<br/>(web app)
participant API
participant DB as PostgreSQL
participant W as Worker
participant P as SMS or email<br/>provider
Rec->>API: POST /recruit/<br/>inbox/messages
API->>DB: Claim the<br/>idempotency key
API->>DB: Lock conversation,<br/>read candidate
API->>DB: Check consent,<br/>sender, cap and<br/>the other rules
alt Refused
API->>DB: Message canceled,<br/>with the reason
API-->>Rec: Not accepted,<br/>with the reason
else Accepted
API->>DB: Message queued,<br/>or scheduled for<br/>the window
API-->>Rec: Accepted
end
loop Every second
W->>DB: Messages due?
end
W->>DB: Lock due messages,<br/>priority 0 first
W->>DB: Read consent and<br/>the other rules again
W->>DB: Cancel what is not<br/>allowed, reserve<br/>the rest
W->>P: Send through<br/>the adapter
alt Accepted by the provider
P-->>W: Message id
W->>DB: Message sent
else Temporary failure
W->>DB: Stays queued,<br/>tried again later
else Definitive failure
W->>DB: Message failed,<br/>with the reason
end
P->>API: Status webhook
API->>DB: Delivered<br/>or failed
- A module calls
MessageSendService(apps/api/src/modules/platform-messaging/message-send.service.ts), the only public entry. It writes inside the transaction of the caller and never calls a provider. The same idempotency key never sends twice: a repeated call returns the first message. - The checks run in a fixed order, and the first that fails is the reason stored in
messages.status_reason:- the candidate is archived (
candidate_archived); - there is no phone or email, or the address typed is not the primary one (
no_destination,unverified_destination); - for SMS, the candidate has no consent or asked to stop (
no_consent,opted_out); for email, the address is suppressed (suppressed); - the company has no approved SMS number, or no reply-to address where the email provider needs one (
sender_not_approved,no_reply_address); - for automatic SMS, the daily cap per candidate is reached (
daily_cap). A message past the cap is discarded, not delayed; - a variable of the template has no value (
template_variable_missing); - for an automatic email, the company has no careers page address to host the unsubscribe link (
careers_address_required).
- the candidate is archived (
- A refusal is a row too: the message is stored as
canceledwith its reason and returned to the caller. No caller, origin or permission can skip a refusal. The one exemption is the confirmation the system sends in reply to STOP, START and HELP, which is written by a service private to the messaging module. - The allowed window applies to automatic origins (
automation,sequence,broadcast,reminder). Outside the window of the company, in the time zone of the candidate, the message is stored asscheduledwith the instant the window opens. A message typed by a person and a system notice leave at once. - Nothing notifies the worker. Its pass, once a second, asks the database which companies have a message due (
platform-messaging/send-queue.runner.ts). Each company gets one reservation per second, guarded by a key in Redis, so the limit per second of its SMS number holds with several worker instances. - Consent, phone, archiving and suppression are read again at the reservation, because a scheduled message may leave hours after it was accepted. A message whose conditions changed is canceled then. The messages are read once more right before the provider call, so a STOP that arrives in between still stops them.
- The adapter only carries the message and translates the format of its provider (the interfaces are in
platform-messaging/providers.ts). It never decides whether a message may leave, and it writes the database in one case only: when Twilio refuses a message because the phone opted out with the provider, the adapter records the withdrawal of consent. Links that carry a token (unsubscribe, scheduling, signing, full application) and email attachments are produced at this moment and are never stored in the message row. - A temporary failure keeps the row and waits longer each time: 30 seconds, 2 minutes, 10 minutes, 30 minutes. The fifth failed attempt ends the message as
failed. An SMS provider that does not answer in 15 seconds ends the message asfailedand is never retried, because the provider may have accepted it and a second call could deliver the same text twice. - Delivery is confirmed by the status webhook of the provider, which finds the company from the provider message id. A status never goes back: a notice that is repeated or arrives out of order changes nothing. With the simulator, a delayed job marks the message delivered.
The rules of consent, STOP, the window and the cap are explained in Messaging.