Skip to content

Solution strategy

This page lists the choices that shape everything else in the system. It is section 4 of the arc42 template. Each choice links to its architecture decision record (ADR), which has the context, the options that were considered and the consequences.

  1. One deployable back end, cut into modules with a public interface. The product spans ten business areas that share people, files and messages, and a single team builds it.
  2. The database enforces the isolation between companies. Application code cannot forget a filter that the database applies by itself.
  3. Every sensitive operation has exactly one path through the code. A message, a document, a signature, a stage change and a change to a driver file each go through one service, which is where the rules live.
  4. Everything outside the system sits behind an adapter with a local stand-in. The whole product runs and is tested without any provider account.
  5. The contract and the appearance are generated or centralized, never repeated. Front ends call the API through a generated client and draw screens only with shared tokens and components.

The goals are the ones of Introduction and goals, in the same order.

Quality goal Approach Decisions
Isolation between companies One database, tenant_id on every business table, forced row level security, the company set at the start of each transaction. Flows without a session enter through owner functions of the gate schema that resolve the company from a public identifier and return only ids. The platform team is a separate identity that reaches company data only through functions of the staff schema. ADR-0002, ADR-0003, ADR-0023
Protection of personal data Column encryption of Social Security number, date of birth and license number, masked in every answer, revealed only with a permission and a log entry. A separate vault for the drug and alcohol file. Sessions and public tokens stored only as hashes. A private bucket whose files are served by the API. ADR-0015, ADR-0016, ADR-0018, ADR-0024, ADR-0017
Traceability for an audit An audit row in every write, checked at the end of each request. Registers are archived, never deleted. Signatures are produced in-house with a proof page. Compliance rules are marked as a regulatory preview until validated. ADR-0011, ADR-0014, ADR-0019
Lawful and timely messaging A single send path that checks consent, opt-out, allowed hours and the daily cap before a message is queued, with a worker that sends it. ADR-0012, ADR-0006
Ease of change Modular monolith with enforced boundaries, a generated API client, a design system used only through tokens, and providers behind adapters. ADR-0001, ADR-0027, ADR-0005, ADR-0010, ADR-0013
Choice What it means in the code Decision
Modular monolith apps/api is one NestJS application. Each business block is a folder of src/modules that other modules reach only through its index.ts; a lint rule and a test enforce it. See Building blocks. ADR-0001
A separate worker over the same code apps/worker hosts the queue consumers that apps/api exports. Work is queued in Redis with BullMQ. Recurring routines ask the database which companies have work due, through gate.tenants_with_due_work, and then open one transaction per company, so the worker never reads across companies. ADR-0006
Domain events through an outbox A module emits an event in the same transaction as the change (emitDomainEvent). The worker delivers it to the consumers that registered for it. Modules react to each other without importing each other. ADR-0025
Shared platform services as modules of their own Messaging, signing, the automation engine and the account email queue are folders of src/modules that import no business module. Business modules register their triggers, resolvers and listeners in them, so sharing a service never closes an import cycle. ADR-0027
One repository Applications and shared packages live in a pnpm workspace with Turborepo tasks. Tool versions are declared once, in the catalog of pnpm-workspace.yaml. ADR-0009
Choice What it means in the code Decision
PostgreSQL with row level security per company The API and the worker connect as ochema_app, a role without BYPASSRLS. withContext (packages/db/src/context.ts) sets app.tenant_id and app.user_id for one transaction; the policies read them. Without a context, a query returns no rows. ADR-0002
The gate schema for paths without a session Sign-up, sign-in, public pages, webhooks and link tokens have no company in a session. They call SECURITY DEFINER functions owned by a role without login, which find the company from a public identifier instead of taking it as a parameter. ADR-0003
Versioned migrations The schema is declared with Drizzle in packages/db/src/schema, and every change ships as a numbered SQL file in packages/db/migrations, applied by a role that the applications do not use. ADR-0004
Archive instead of delete Registers carry archived_at. The default lists show active rows only, and the application role has no DELETE on those tables. ADR-0011, which replaced ADR-0021
UUID version 7 keys and monthly partitions Primary keys default to uuidv7(). The two audit logs, messages, domain events and the file access log are partitioned by month from their first migration. ADR-0028
Text search through functions that return ids Search by part of a name uses one function of the search schema per table. It reads the company from the transaction context and returns only ids, which the API then loads under row level security. ADR-0022
Files in S3-compatible storage The database keeps the metadata and the access log of a file; the bytes go to object storage under a key that starts with the company. Documents go through FileService; the logo of a careers page, an import spreadsheet and an audit export are kept by the module that owns them, under the same company prefix. ADR-0017
Choice What it means in the code Decision
REST with an OpenAPI document generated from the code Routes declare their schemas with Zod. packages/contracts/openapi.json is generated from the API code, and the typed client is generated from that file. Front ends import the client; a lint rule forbids hand-written HTTP calls. ADR-0005
React with Vite for the product The office system and the driver app are single page applications that share packages/app-kit. The driver app is an installable progressive web app in version 1.0; native apps come after it. ADR-0007, ADR-0026
Opaque cookie sessions A session is a random token in an HttpOnly cookie, stored as a hash and resolved in the database on each request. Requests from another site are refused by an origin check. ADR-0024
Astro for the public sites The landing site and this documentation are static. The careers site is rendered on the server, so an unpublished job answers 404 at once and the pages ship little or no script. ADR-0008, ADR-0020
A design system used only through tokens packages/ui is the only place where a colour, a font, a radius or a spacing value is written. Lint rules reject them anywhere else, so the whole look can be replaced by changing tokens and theme. ADR-0010

A rule that must always hold is written once, in one service, and every caller goes through it. The services below are the public interface of their modules.

Operation The one path Rules that live there Decision
A message leaves MessageSendService, in platform-messaging Consent, opt-out, suppression, allowed hours, daily cap, idempotency key. A refusal is recorded with its reason. ADR-0012
A provider is called SmsProvider, EmailProvider and the calendar gateways The adapter is chosen by configuration; the default is a simulator. ADR-0013
A document is signed SigningService, in platform-signing Content frozen with its hash, signers in order, proof pages, final PDF checked against the recorded hash. ADR-0014
A document enters or leaves FileService, in core/storage Type checked by the first bytes, size limits, access decided by the owner a module registered, every read logged. ADR-0017
Sensitive data is written or shown SensitiveData, in core/sensitive AES-256-GCM per value, masked answers, reveal with permission and log entry. ADR-0015
A drug or alcohol record is read Policies that call app.has_permission Without compliance.drug_alcohol.read, the rows do not exist for the session, in any query of any module. ADR-0016
A public link is opened gate.public_context_by_* functions Only the SHA-256 of a token is stored and compared; expired and revoked links resolve to nothing. ADR-0018, ADR-0003
A lead enters LeadIntakeService, in recruit Matching against existing candidates, consent capture, source attribution, screening answers, distribution and score, for the public form, the lead API, the import and a recruiter alike. None
An application changes stage or status ApplicationMoveService, in recruit Stage moves, closing with a reason, reopening and hiring. None
A driver file changes ComplianceEngine, in compliance Which items a driver needs, their state, and eligibility. Rules are a regulatory preview until validated. ADR-0019
  • Row level security shapes queries. A text search cannot use its index through a policy, so search goes through dedicated functions of the search schema that return ids (ADR-0022). Every critical query has its plan checked against a seed of realistic volume.
  • A single deployable scales as a unit. The split that exists is between the API and the worker. Splitting a module out would start from its public interface. See ADR-0001.
  • Simulators are not providers. The real adapters are written against the documentation of each provider and tested locally. Sending through a real account is Not verified. See Context and scope.
  • In-house signing and in-house compliance rules carry legal weight. That is why rules are labelled as a preview until the platform team validates them, and why the limits are stated in Risks and known limitations.