Skip to content

Context and scope

This page draws the line around Ochema: who uses it, which systems it talks to, and what stays outside. It is section 3 of the arc42 template and level 1 of the C4 model.

flowchart LR
  subgraph carrier["Carrier staff"]
    recruiter(["<b>Recruiter</b><br/>[Person]"])
    officer(["<b>Compliance officer</b><br/>[Person]"])
    owner(["<b>Owner</b><br/>[Person]"])
  end

  subgraph outside["People outside the carrier"]
    applicant(["<b>Applicant</b><br/>[Person]"])
    driver(["<b>Driver</b><br/>[Person]"])
    employer(["<b>Previous employer</b><br/>[Person]"])
  end

  staff(["<b>Platform team</b><br/>[Person]"])
  leads[["<b>Lead source</b><br/>[External system]<br/>In use"]]

  ochema["<b>Ochema</b><br/>[Software system]<br/>Driver recruiting<br/>and compliance<br/>for US carriers"]

  sms[["<b>SMS provider</b><br/>[External system]<br/>Simulator"]]
  email[["<b>Email provider</b><br/>[External system]<br/>Simulator"]]
  calendar[["<b>Calendar providers</b><br/>[External system]<br/>Simulator"]]
  storage[["<b>Object storage</b><br/>[External system]<br/>In use"]]
  screening[["<b>Screening providers</b><br/>[External system]<br/>Planned"]]

  recruiter -->|"Recruits,<br/>hires"| ochema
  officer -->|"Keeps<br/>driver files"| ochema
  owner -->|"Administers<br/>the company"| ochema
  applicant -->|"Applies,<br/>signs"| ochema
  driver -->|"Sends files,<br/>signs"| ochema
  employer -->|"Answers<br/>a request"| ochema
  staff -->|"Operates<br/>the panel"| ochema
  leads -->|"Sends<br/>leads"| ochema

  ochema <-->|"SMS out,<br/>replies in"| sms
  ochema <-->|"Email out,<br/>replies in"| email
  ochema <-->|"Busy times in,<br/>interviews out"| calendar
  ochema -->|"Files in<br/>and out"| storage
  ochema -.->|"Reports<br/>(Planned)"| screening

Legend. Rounded shape: a person. Plain box: the software system this documentation describes. Box with double side borders: a system outside Ochema. Solid arrow: a relationship that exists in the code. Dashed arrow: Planned. The last line of an outside system is the state of the integration, in the words defined below. The grouping boxes only organize the people; they are not systems.

The SMS and email providers also deliver to the people: a text message or an email reaches the applicant, the driver or the previous employer through them. Those arrows are left out to keep the diagram readable. The calendar applications that subscribe to the interview feed of a recruiter are left out too; they are in the table of outside systems below.

Person What they do in Ochema Where
Recruiter Receives leads, moves applications through the pipeline, writes to candidates by SMS and email, books interviews, sends offers and hires. Office system (apps/web), modules Attract and Recruit
Compliance officer Keeps the driver qualification file of each driver, records screenings and exams, requests safety performance history from previous employers, exports files for an audit. Office system, module Compliance
Owner Creates the company account, edits company details, invites users, defines roles and permissions, switches modules on and off, sets up messaging, calendars and API keys. Office system, module Platform
Applicant Finds a job on the careers page, applies from a phone without a password, books an interview, fills the full application, uploads documents and signs. Careers site (apps/careers), by public page or by link
Driver After hiring, uploads the documents that are missing or expiring and signs contracts in the same link-based area the applicant used. The installable driver app has sign-in and empty Home, Loads, Documents and Messages screens; its features are Planned. Careers site, area /<company>/my/<token>; driver app (apps/driver)
Previous employer Receives an email with a link, reads the signed authorization of the driver and answers the safety performance history questions. Has no account. Careers site, page /verify/<token>
Platform team Operates the platform across companies: company list and status, validation of compliance rules and consent texts, legal texts, SMS numbers and carrier registration, the OAuth applications of the calendars. Not a user of any company. Platform panel, /admin in apps/web

“Recruiter” and “Compliance officer” are jobs, not fixed roles of the product. Every company starts with three system roles, Owner, Admin and Read only (roles.system_key), and defines its own roles on top of the permission catalog. See Authentication and permissions.

Each integration is behind an adapter interface, and the adapter is chosen by configuration (apps/api/src/core/config/config.ts). The state uses three words:

  • In use: the product runs against a real system of this kind today.
  • Simulator: the adapter for the real provider is written, and the default configuration binds a local stand-in instead. No provider account is needed to run the product.
  • Planned: no adapter exists in the code.
System State What Ochema uses it for
SMS provider Simulator Text messages to candidates. Replies, STOP keywords and delivery status come back by webhook.
Email provider Simulator Email to candidates, drivers and previous employers, and account email such as invitations and password resets. With Amazon SES, replies, bounces and complaints come back through Amazon SNS webhooks.
Calendar providers Simulator Reads when a recruiter is busy (start and end only, never the title or the participants) and writes booked interviews to the recruiter’s calendar, by OAuth.
Object storage In use Every file: uploads of users, applicants and third parties, generated PDFs, audit exports. The bucket is never public; the API decides who reads a file and serves its bytes.
Lead source In use A carrier website or another system sends leads to POST /public/v1/leads with Authorization: Bearer <key>. Keys are created in Platform > Integrations and stored only as a SHA-256 hash.
Calendar applications In use A recruiter subscribes any calendar application to an iCalendar feed of their interviews, GET /public/interview-calendars/{file}, identified by a token in the address.
Screening providers and agencies Planned Motor vehicle records, background checks, PSP reports, drug and alcohol tests and Clearinghouse queries. Today the company orders each one on the provider’s own site, and Ochema records what to order, the file received, the result, the date and the reviewer, in Compliance > Screenings.

Where each state comes from in the code:

System Adapter Default binding
SMS provider Twilio: providers/twilio, in apps/api/src/modules/platform-messaging SMS_PROVIDER=simulator. The worker keeps the message, logs it and marks it delivered after a configurable delay (simulator.ts). Test routes inject replies; they are not mounted in production.
Email provider SMTP and Amazon SES: providers/smtp and providers/ses, in the same module EMAIL_PROVIDER=outbox and MAIL_TRANSPORT=outbox. Every email is written as a file to a local folder and to the worker log.
Calendar providers Google Calendar and Microsoft Graph: google.gateway.ts and microsoft.gateway.ts, in apps/api/src/modules/platform/calendar CALENDAR_ADAPTERS=real binds the two adapters, which stay idle until the platform team saves an OAuth application in the platform panel. The automated tests bind fake.gateway.ts, which production refuses.
Object storage Any S3-compatible service: object-storage.ts, in apps/api/src/core/storage The S3_* variables. In development, the s3 service of docker-compose.yml.
Lead source Inbound API: public-api, in apps/api/src/modules/recruit Always on.
Calendar applications Inbound feed: calendar-feed.controller.ts, in apps/api/src/modules/recruit/interviews Always on.
Screening providers and agencies None Not applicable

Three notes on the tables:

  • The Twilio, SMTP, Amazon SES, Google Calendar and Microsoft Graph adapters are tested against local stand-ins. Sending through a real provider account is Not verified.
  • Choosing a real provider is a configuration change, not a code change. With SMS_PROVIDER=twilio, EMAIL_PROVIDER=smtp or EMAIL_PROVIDER=ses, the API and the worker refuse to start while a required setting is missing, and the error names it.
  • Integrations with telematics or ELD providers, accounting systems, job boards and advertising platforms are Planned and have no code.
Channel Protocol and format Notes
Browser to the office system and the driver app HTTPS, JSON over REST, httpOnly session cookie Calls go only through the client generated from the OpenAPI document. The API accepts the origins listed in CORS_ORIGINS. See API contract.
Browser to the careers site HTTPS, server-rendered HTML The browser never calls the API. The careers server calls the public routes on behalf of the visitor and sends the link token in a header, never in the address.
SMS provider to Ochema HTTPS webhooks The signature of every webhook is checked against the configured public address of the API, not against the Host header. The routes answer 404 unless SMS_PROVIDER=twilio.
Email provider to Ochema HTTPS notifications from Amazon SNS Signature checked, and only the two configured topics are accepted. The routes answer 404 unless EMAIL_PROVIDER=ses.
Ochema to the email provider SMTP with STARTTLS or TLS, or the Amazon SES API With SMTP in production, the TLS upgrade is mandatory.
Ochema to calendar providers HTTPS, OAuth 2.0 authorization code with PKCE Client secrets and tokens are stored encrypted with SECRETS_ENCRYPTION_KEY.
Ochema to object storage S3 API Keys always start with the company: tenants/<tenant_id>/....
Lead source to Ochema HTTPS, JSON, bearer key Rate limited per key and per IP.
  • Ochema records the result of a screening; it does not perform one.
  • Ochema does not register a carrier with the phone carriers for text messaging. The registration belongs to each carrier, and the platform panel only records its situation.
  • Compliance rules ship as a regulatory preview. A rule is treated as definitive only after the platform team marks it validated. See ADR-0019.
  • Fleet, load operations, customer portals and finance are in the product plan and mostly Planned. The capability map shows the state of each one.
  • Building blocks: what is inside the Ochema box.
  • Messaging: consent, STOP, allowed hours and the single send path.
  • ADR-0013: providers behind adapters with a simulator.
  • ADR-0017: S3-compatible file storage.