Skip to content

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.

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_id and app.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 a gate.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.

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
  1. 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, through gate.public_context_by_slug. The route answers 202 in every case, so a visitor cannot tell whether a candidate already existed.
  2. 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 event application.created in the outbox. This is the only event type of the priority lane, 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 the default lane instead.
  3. 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 on events-consume-priority and marks the events dispatched in the same transaction.
  4. The automation engine (platform-automations/automation-engine.ts) is one of the consumers. For each enabled rule the event triggers, it creates one row of automation_runs and the rows of automation_run_actions. An application created as not qualified starts no run.
  5. 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 key first_contact:<candidate>:<day>. A second application of the same candidate on the same day sends nothing, and an imported application never gets the message.
  6. 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.
  7. The sending pass reserves the message, calls the provider through its adapter and records the result. When the message becomes sent, applications.first_response_seconds is 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.

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
  1. “Send full application” is POST /recruit/applications/{id}/full-application/send (recruit/full-application/full-application.service.ts). It creates the row of driver_applications and 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 in messages.body.
  2. 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, through gate.public_context_by_full_application_token. A token that is unknown, expired, canceled or of another company gets the same answer.
  3. The steps are saved one at a time (PUT .../steps/personal, addresses, licenses, employments, history, questions and documents). The Social Security number and the date of birth are encrypted before they are written. See Sensitive data.
  4. signature/prepare refuses 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 (queue platform-signing) and kept in the object storage, so the envelope is draft for a moment and then sent.
  5. signature requires the typed name to match the legal name of step 1 and the IP address of the visitor. The signing service writes the proof in signing_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 signed and read only, and emits full_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.
  6. 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-APP of the driver file, and the candidate gets a copy by email.

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
  1. POST /recruit/applications/{id}/hire needs two permissions, recruit.applications.hire and people.directory.manage (recruit/hiring/hiring.service.ts). Everything below happens in the transaction of that request; a failure in any step leaves nothing written.
  2. 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 reason hired_elsewhere. When the application has a signed full application, its encrypted Social Security number, date of birth and current license number are copied to person_identity of the person, without being decrypted (see Sensitive data).
  3. The driver file of the application becomes the file of the person in one UPDATE of one row: person_id is set and phase becomes active. 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.
  4. The worker dispatches application.hired to its consumers. compliance.onboarding-hire starts the onboarding plan of the person, when the company has an onboarding template that applies. compliance-engine repeats the driver file step and finds nothing to change. An automation rule triggered by the hire starts here too.
  5. 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.
  6. After each recalculation the engine stores status, eligible and ineligible_reasons on 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
  1. 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.
  2. 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 messages keeps neither the token nor the file.
  3. 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, through gate.public_context_by_safety_history_token. A token that is unknown, expired, replaced, or of a request already answered or canceled gets the same 404.
  4. The page calls respond twice with the same body. The first call freezes the answers about employment and accidents as the document of a signing envelope and answers submitted: false. Once the worker has stored the PDF, the second call signs it.
  5. 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 status answered, or no_record when 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.
  6. The engine approves the item of the driver file when every request of the file has an answer, or a documented lack of one.
  7. Without an answer, the worker sends reminders 7, 14 and 21 days after the request and closes it as no_response the day after the 30-day deadline. A late answer is still accepted.

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
  1. POST /compliance/audit-export/exports needs compliance.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 needs compliance.sensitive_data.reveal.
  2. The job is queued after the transaction commits (queue compliance-exports). A pass once a minute also picks up any export still queued, so a lost job does not leave an export waiting forever.
  3. 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 in file_access_log with the purpose export. 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.
  4. 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.
  5. 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.
  6. The download checks that the export is completed and not expired, writes the audit row compliance.audit_export.downloaded, and compares the size and the SHA-256 hash of the stored file with the ones recorded before sending it.
  7. After 7 days the worker deletes the file from the storage and the row stays, as expired.

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
  1. 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.
  2. 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).
  3. A refusal is a row too: the message is stored as canceled with 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.
  4. 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 as scheduled with the instant the window opens. A message typed by a person and a system notice leave at once.
  5. 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.
  6. 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.
  7. 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.
  8. 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 as failed and is never retried, because the provider may have accepted it and a second call could deliver the same text twice.
  9. 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.