Skip to content

Introduction and goals

This page says what the system is for and what the architecture has to protect. It is section 1 of the arc42 template.

Ochema is a platform for trucking and delivery companies in the United States. It brings into one system the work that starts when a company needs a driver and continues for as long as that driver works there: attracting applicants, recruiting them, hiring, keeping the driver qualification file in order, and, later in the plan, running the fleet, the loads and the money.

The product is built in the order a carrier needs it. Recruiting and compliance come first and work on their own, with or without the logistics modules.

Decision about the product What it is
Market United States only. The product is in English and Spanish.
Customer Freight carriers with CDL drivers, and last mile delivery companies with drivers who need no CDL. Any size, from one vehicle up.
Offer Software and service. It starts with recruiting and processing, which does not depend on the logistics modules.
Driver app A progressive web app in version 1.0. Native apps come after it.
Compliance The rules ship as a regulatory preview. Each rule is treated as definitive only after it is marked validated in the platform panel.
Screenings Orders to agencies and providers are recorded, not integrated. Integration with a screening partner is Planned.

Source: docs/arquitetura.md, checked against the code.

The scope of the product is organized in ten blocks, A to J, and each block is one module of the system with the same name in the code, in the office system and in this documentation. The feature survey of the product (docs/levantamento.md) lists 288 features across the ten blocks.

The table says what each module has in the API today. The state of every capability, as Available, Preview, Planned or Not planned, is in the capability map.

Block Module What the API has today
A Attract Jobs, the careers page, campaigns and tracked links, referrals, leads, broadcasts, analytics.
B Recruit Candidates and applications, the pipeline, the inbox, call lists, message templates, sequences, automations, interview scheduling, scorecards, offers, hiring, import, analytics.
C Compliance Document types and rules, driver files, credentials, screenings, the drug and alcohol file, safety performance history, contracts, onboarding, expirations, audit export, the candidate and driver area.
D People The directory of people and the terminals.
E Fleet The register of vehicles.
F Operations The registers of customers and locations.
G Driver app The access check of the module. The app itself has sign-in and empty screens.
H Portals The access check of the module.
I Finance The access check of the module.
J Platform Sign-up and sign-in, users, roles and permissions, company details, module switches, the audit log, Home, search, integrations, and the platform panel.

Source: the folders and controllers of apps/api/src/modules. See Building blocks.

Three flows define the product and are the ones the architecture is tuned for:

  1. From lead to first contact. A lead arrives by the careers page, the lead API, an import or a recruiter, and the first message can go out without anyone having to act, through the “First response” automation, which a company turns on.
  2. From applicant to signed hire. The candidate applies from a phone without a password, books an interview, fills the full application, receives an offer and signs.
  3. From hire to an eligible driver. Hiring opens the driver file, the missing documents and screenings are collected, previous employers are asked for the safety history, and the file can be exported for an audit.

Each one has a sequence diagram in the runtime view.

These are the five qualities the architecture is built around, in order of precedence: when two of them pull apart, the one higher in the list wins. The measurable requirements derived from them, each with its evidence and state, are in Quality requirements.

# Goal What it means How the code gives it precedence
1 Isolation between companies A user, a public link or a background job of one company never reads or changes the data of another, even when application code forgets a filter. Row level security is forced on every business table, and the application role cannot bypass it. Where a policy would stop an index from being used, the code adds a dedicated function instead of relaxing the policy. See Tenant isolation.
2 Protection of personal data Social Security numbers, dates of birth and license numbers are unreadable at rest and masked on screen. Drug and alcohol results reach only the people with that permission. Without the encryption key, the routes that write or reveal these values answer 503 and write nothing: the system prefers being unavailable to storing a value in clear. See Sensitive data.
3 Traceability For any record, the company can show who changed what and when, and nothing an audit may ask for disappears. A write request that records no audit row fails and is rolled back. Registers are archived, not deleted. See Audit log and Archiving.
4 Lawful and timely messaging No message reaches a person who did not consent, who opted out, or outside the allowed hours; within those limits, a new lead hears from the company fast. Every message goes through one service that refuses first and sends second. A refused message is stored with its reason, not sent late. See Messaging.
5 Ease of change A module can be added, a provider swapped or the whole look replaced without rewriting what already works. Module boundaries, the API client and the use of design tokens are enforced by lint rules and tests, so they do not erode with time. See Solution strategy.

Accessibility, performance, availability and the other qualities are requirements of the product too. They are listed with their state in Quality requirements; the five above are the ones that decide the shape of the system.

Who What they need from this documentation
A carrier evaluating Ochema What the product does today and what is Planned: the capability map and the roadmap.
A security or compliance reviewer of a carrier How data is isolated and protected, and what is recorded: the cross-cutting concepts, Quality requirements and Risks and known limitations.
An integrator How systems connect: Context and scope, the API contract and the API routes.
A developer of the product How the code is organized and why: Building blocks, Solution strategy and the architecture decisions.
The platform team Where things run and what a production environment needs: the Deployment view.
People who use the product every day The User guide, not this documentation.