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.
How to read the diagrams
Section titled “How to read the diagrams”- Every box is a table, with its real name. The schema is defined in
packages/db/src/schemaand created by the versioned migrations inpackages/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_idcolumn that referencestenants, and a row level security policy on it. Foreign keys between two company tables includetenant_idon both sides, so a row can never point at a row of another company. To keep the diagrams readable, the line totenantsis drawn only in the first diagram, and only for the tables that define who belongs to a company. See Tenant isolation.
Company and identity
Section titled “Company and identity”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.
Attraction and recruiting
Section titled “Attraction and recruiting”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.
Messages and automations
Section titled “Messages and automations”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 onoccurred_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.
Compliance
Section titled “Compliance”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.