Skip to content

Domain model

This page shows the entities that carry the product and the relationships between them, one diagram per area. It is a map, not a catalog: the complete list of tables, by module, is in Database tables.

  • Every box is a table, with its real name. The schema is defined in packages/db/src/schema and created by the versioned migrations in packages/db/migrations.
  • Every line is a foreign key that exists in the database. A relationship kept only by convention (a column with an id and no constraint) is not drawn; the text below each diagram names the ones that matter.
  • The ends of a line give the cardinality:
Notation Meaning In the database
A ||--o{ B Each B belongs to exactly one A. An A has zero or more B. Foreign key column NOT NULL
A |o--o{ B Each B belongs to at most one A. Foreign key column nullable
A ||--o| B An A has at most one B, and each B belongs to exactly one A. Foreign key NOT NULL with a unique index
A |o--o| B At most one on each side. Foreign key nullable with a unique index
  • Every table of a company has a tenant_id column that references tenants, and a row level security policy on it. Foreign keys between two company tables include tenant_id on both sides, so a row can never point at a row of another company. To keep the diagrams readable, the line to tenants is drawn only in the first diagram, and only for the tables that define who belongs to a company. See Tenant isolation.

A person who signs in is a row of users, which belongs to no company. What ties a user to a company is a membership, and the membership carries the role.

erDiagram
  tenants ||--o{ memberships : has
  users ||--o{ memberships : joins
  roles ||--o{ memberships : "assigned to"
  tenants ||--o{ roles : defines
  roles ||--o{ role_permissions : holds
  permissions ||--o{ role_permissions : "granted in"
  tenants ||--o{ tenant_modules : switches
  users ||--o{ sessions : opens
  memberships |o--o{ sessions : "active in"
  memberships |o--o| people : "account of"
  terminals |o--o{ people : "home of"
Table What it holds
tenants One row per company: name, time zone, default language, address, USDOT and MC numbers. status is active or suspended.
users One row per account, unique by email across the platform. It has no tenant_id.
memberships A user in a company, with exactly one role. Unique per company and user. status is active or disabled.
roles The roles of a company. Three are created with the company and identified by system_key: owner, admin and read_only.
permissions The global catalog of permission keys, such as recruit.offers.manage. It has no tenant_id.
role_permissions Which permissions a role grants.
tenant_modules Whether a product module is on for the company, one row per company and module.
sessions A signed-in session. Only the SHA-256 hash of the session token is stored. The active company of a session is a membership of the same user.
invitations A pending invitation to join a company with a role (it references roles). Only the hash of the invitation token is stored. Not drawn.
terminals The operating locations of a company. A terminal can name a person as its manager.
people The directory of the company: drivers and office staff. role is one of driver, helper, dispatcher, mechanic, recruiter or office; status is active, on_leave or terminated. A person may be linked to one membership (user_id), and each membership to at most one person. A person can report to another person (manager_person_id).

The platform team is kept apart from company users: platform_staff, platform_staff_sessions and platform_staff_invitations have no relationship to users or memberships. See Authentication and permissions.

A candidate is a person known to the company. Every interest of a candidate in a job is an application, and the application is what moves through the pipeline. The first diagram shows how an application arrives.

erDiagram
  jobs ||--o{ job_screening_questions : asks
  jobs |o--o{ campaigns : "advertised by"
  campaigns |o--o{ tracked_links : groups
  jobs |o--o{ tracked_links : "target of"
  jobs |o--o{ applications : receives
  candidates ||--o{ applications : "applies with"
  applications ||--o{ lead_touches : "arrived by"
  tracked_links |o--o{ lead_touches : "source of"
  applications ||--o| referrals : "came from"
  people ||--o{ referrals : refers

The second diagram follows an application through the pipeline, up to the hire.

erDiagram
  memberships |o--o{ candidates : "recruiter of"
  candidates ||--o{ applications : "applies with"
  pipeline_stages ||--o{ applications : "stage of"
  applications ||--o{ application_stage_changes : history
  applications ||--o{ interviews : schedules
  interview_types ||--o{ interviews : "kind of"
  interviews ||--o{ interview_scorecards : "rated in"
  applications ||--o{ offers : receives
  applications ||--o| driver_applications : "completed as"
  candidates |o--o| people : became
  applications |o--o| people : "hired as"
Table What it holds
jobs A job opening. status is draft, open, paused or closed.
job_screening_questions The screening questions of a job, with the knockout rule of each.
campaigns, tracked_links A recruiting campaign and its short links (/r/<code>). A referral link belongs to the person who refers.
candidates One row per person, unique by email and by phone inside the company. Holds the SMS consent flag, the preferred language and the recruiter.
applications The candidate in the pipeline of a job. Holds the stage, the status, the source and the screening result. One active application per candidate and job.
pipeline_stages The stages of the company pipeline. kind is open, hired or not_qualified; a company has at most one active stage of each of the last two kinds.
application_stage_changes One row per move, with the stage before and after and the reason.
lead_touches Every arrival of a lead: channel, campaign, tracked link, API key or import batch. An application can have several.
application_screening_answers The answers given, each marked as passing or failing its knockout rule. References the application and the question. Not drawn.
candidate_events The timeline of the candidate. Not drawn.
interview_types, interviews, interview_scorecards Interview kinds, booked interviews and the scorecard each interviewer fills in.
offers A job offer for an application, signed through a signing envelope. At most one open offer per application.
referrals The referral that produced an application, with the bonus.
driver_applications The complete driver employment application (the 49 CFR 391.21 form) of an application of the pipeline. It is described under Compliance.

Two links tie recruiting to the directory. candidates.person_id points to the person the candidate became, and people.hired_from_application_id points to the application that hired the person. Both are written by the Hire action, in one transaction.

The public careers page of a company is one row of career_sites, unique per company and by slug across the platform.

Every SMS and email, sent or received, is a row of messages. Automatic sends come from three sources (automation rules, sequences and broadcasts), and all of them write through the same sending service.

erDiagram
  candidates ||--o{ candidate_consents : "gives or withdraws"
  consent_texts |o--o{ candidate_consents : "wording of"
  candidates |o--o{ conversations : "talks in"
  conversations |o--o{ messages : contains

Sequences and broadcasts are the two ways to write to many candidates. Both take their text from a template.

erDiagram
  sequences ||--o{ sequence_steps : steps
  message_templates ||--o{ sequence_steps : "text of"
  sequences ||--o{ sequence_enrollments : enrolls
  candidates ||--o{ sequence_enrollments : "enrolled in"
  message_templates ||--o{ broadcasts : "text of"
  broadcasts ||--o{ broadcast_recipients : audience
  candidates ||--o{ broadcast_recipients : "listed in"

Automation rules have their own tables. A run points to the saved version of the rule it executes, not to the rule as it is now.

erDiagram
  automation_rules ||--o{ automation_rule_actions : actions
  automation_rules ||--o{ automation_rule_versions : versions
  automation_rule_versions ||--o{ automation_runs : "executed as"
  applications |o--o{ automation_runs : "subject of"
  automation_runs ||--o{ automation_run_actions : steps
Table What it holds
candidate_consents The consent ledger: one row each time a candidate gives or withdraws consent for a channel (sms, voice, email, ai_contact, call_recording), with the exact text shown. Rows are only added.
consent_texts The global catalog of consent wordings, by channel, language and version. It has no tenant_id.
conversations One thread per candidate and channel (sms or email). A conversation without a candidate is an unknown sender. status is open or done.
messages Every message, inbound and outbound, partitioned by month on created_at. An outbound row also is the item of the sending queue.
message_templates Reusable texts, by channel and language.
sequences, sequence_steps, sequence_enrollments A timed series of messages and the candidates going through it.
broadcasts, broadcast_recipients A one-time send to an audience, with the outcome per recipient.
automation_rules, automation_rule_actions A rule: a trigger, conditions and ordered actions.
automation_rule_versions A snapshot of the rule each time it is saved. A run executes the version that was current when it started.
automation_runs, automation_run_actions One execution of a rule and the result of each action.

Three more tables complete the area and stand alone:

  • messaging_settings: one row per company, with the SMS number, the reply-to address, the allowed sending window and the daily cap of automatic SMS.
  • email_suppressions: the addresses a company may not email (unsubscribed, bounced or complained).
  • domain_events: the outbox of business events that feeds the automations, partitioned by month on occurred_at.

The two partitioned tables keep most of their references as plain id columns, with no constraint: messages has one foreign key to a business table (conversation_id) and domain_events has none. messages.application_id, messages.template_id, messages.automation_rule_id, messages.sequence_id and messages.broadcast_id are read as ids. See Messaging and Background work.

The center of compliance is the driver file. It is born with an application during hiring, follows the application to the person at the hire, and holds one item per requirement.

erDiagram
  applications |o--o| driver_files : "file in hiring"
  people |o--o{ driver_files : "file after hire"
  driver_files ||--o{ compliance_items : requires
  compliance_rules |o--o{ compliance_items : "source of"
  compliance_document_types |o--o{ compliance_items : "source of"
  compliance_items ||--o{ compliance_item_files : documents
  files ||--o{ compliance_item_files : "stored as"
  compliance_items ||--o{ compliance_item_events : history
  driver_files ||--o{ screening_requests : screenings
  compliance_items |o--o{ screening_requests : "fulfilled by"
Table What it holds
driver_files The driver qualification file of one application or one person: driver type, phase, stored status, eligibility and the reasons that block it. A person has at most one open driver file; a closed one stays readable.
compliance_rules The global catalog of requirements, each with its regulation reference. It has no tenant_id.
compliance_rule_settings The switch of a catalog rule for one company. Not drawn.
compliance_document_types Document types the company adds on top of the catalog.
compliance_items One requirement of one driver file, from a catalog rule or from a company document type. Holds the status, the due date and the expiration date.
compliance_item_files, compliance_item_events The documents attached to an item and its history, one row per change.
files Every stored file. See Files and vaults.
screening_requests A motor vehicle record, PSP report, medical exam, road test or Clearinghouse query requested for a driver file.
drug_alcohol_records The drug and alcohol file, in a separate vault with its own permission. A record references a person or, before the hire, an application. Not drawn.
onboarding_plans, onboarding_tasks The onboarding of a hired person (a plan references people). A task can be tied to a compliance item or to a contract. Not drawn.
compliance_exports, compliance_export_subjects An audit export and the driver files it covers (a subject references the export and the driver file). Not drawn.

The second diagram shows what is signed. Every signature in the product goes through the same four signing tables, whatever the document. An envelope also references files twice, for the PDF to sign and for the final PDF with the proof pages.

erDiagram
  signing_envelopes ||--o{ signing_signers : signers
  signing_signers ||--o| signing_signatures : proof
  signing_envelopes ||--o{ signing_events : trail
  signing_envelopes |o--o{ offers : signs
  signing_envelopes |o--o{ driver_applications : signs
  signing_envelopes ||--o| contract_documents : signs
  driver_files ||--o{ contract_documents : holds
  driver_applications ||--o{ driver_application_employments : declares

The last diagram is the investigation of safety performance history with previous employers. A request is about one employment the candidate declared, and it carries the envelope in which the candidate signed the authorization.

erDiagram
  driver_files ||--o{ safety_history_requests : investigates
  driver_application_employments ||--o{ safety_history_requests : about
  signing_envelopes ||--o{ safety_history_requests : authorizes
  safety_history_requests ||--o{ safety_history_attempts : attempts
  safety_history_requests ||--o| safety_history_responses : answer
  signing_signatures ||--o{ safety_history_responses : "signed with"
Table What it holds
driver_applications The complete application the candidate fills in and signs. The Social Security number and the date of birth are stored encrypted. Its history lives in child tables: addresses, licenses, employments, accidents, violations, gaps and answers.
driver_application_employments The previous employers the candidate declared. Safety history requests are made about these rows.
signing_envelopes One document to sign: its frozen content, the hash of the PDF, the status and the limit date.
signing_signers Who signs an envelope and in which order. role is candidate, driver, third_party or company_user. Only the hash of the signing link token is stored.
signing_signatures The proof of one signature: typed name, IP address, browser, consent text and the hash of the document signed. One per signer.
signing_events The audit trail of the envelope.
contract_documents A contract or policy sent to a driver, one per envelope.
safety_history_requests A request for safety performance history to one previous employer (49 CFR 391.23), with the authorization the candidate signed.
safety_history_attempts Each attempt to reach the employer: the emails sent and the calls, faxes and letters logged by hand.
safety_history_responses The signed answer of the employer. At most one per request.

The states of these records and what moves them are in Lifecycles.