Skip to content

Constraints

This page lists what is fixed before any design choice is made. It is section 2 of the arc42 template. A constraint here is not up for discussion inside a feature: changing one is an architecture decision of its own, recorded as an ADR.

Where a constraint is enforced by a tool, the table says which one. A rule that only lives in a document tends to erode; most of the rules below fail a lint run, a test or the start of a process.

Constraint Detail Where it is set or enforced
Node.js 26 and pnpm 12 node >=26.13.1 <27, pnpm >=12.18.0 <13. engines in the root package.json, .nvmrc
TypeScript in strict mode everywhere strict, noUncheckedIndexedAccess and exactOptionalPropertyTypes, with the strict type-checked ESLint presets. packages/config/tsconfig.base.json, packages/config/eslint.js
PostgreSQL 18 with PostGIS Primary keys default to uuidv7(), a built-in function of PostgreSQL 18. The extensions postgis, pg_trgm, btree_gin, btree_gist and unaccent are required, in the schema extensions. packages/db/sql/bootstrap-roles.sql, packages/db/src/schema/helpers.ts
Redis BullMQ queues and the counters of the request limits. apps/api/src/core/redis, apps/api/src/core/rate-limit
S3-compatible object storage The only place where file bytes are kept. apps/api/src/core/storage
Long-running processes, no serverless functions The API, the worker and the careers server are container images. The other front ends are static files. Dockerfile
The driver app is a progressive web app in version 1.0 Continuous location tracking with the screen off is not reliable in a web app, so tracking in the background is Planned for the native apps. apps/driver, product decision
One version of each tool Versions are declared once in the workspace catalog. Releases published less than one day ago are skipped. pnpm-workspace.yaml
Constraint Detail Where it is set or enforced
One database for every company Every business table has tenant_id and a row level security policy, forced also for the table owner. No exception. Migrations in packages/db/migrations; tests in packages/db/test
The application never bypasses row level security The API and the worker connect as ochema_app, without BYPASSRLS. The controlled exceptions are SECURITY DEFINER functions owned by roles without login. packages/db/sql/bootstrap-roles.sql. See Tenant isolation.
No table, column or index outside a migration The schema changes only through numbered SQL files, applied by the owner role. packages/db/migrations. See ADR-0004.
Registers are archived, never deleted The application role has no DELETE on register tables. The one exception is form rows inside another register, such as the contacts of a customer. Grants in the migrations. See Archiving.
Every write leaves an audit row A write request without one fails and rolls back. transaction.interceptor.ts, in apps/api/src/core/http
Fixed data conventions UUID version 7 primary keys. Instants as timestamptz. Money as whole cents in integer columns. Phone numbers stored in E.164, with the United States as the default region. packages/db/src/schema, apps/api/src/core/validation/fields.ts
High-volume tables are partitioned by date from the start The two audit logs, messages, domain events and the file access log. packages/db/migrations
Constraint Detail Where it is set or enforced
A module imports another only through its public interface No import of an internal file of another module of the API, and no import cycle between modules. Lint rule ochema-api/module-boundary; test module-cycles.test.ts, in apps/api/test
Front ends call the API only through the generated client No hand-written fetch, XMLHttpRequest or HTTP library in the React apps. eslint-react.js, in packages/config
Appearance comes only from packages/ui No colour, font, radius, spacing value or arbitrary Tailwind value in an app. Lint rules ochema/no-hardcoded-style and ochema/no-css-declarations
Platform panel code is fenced Panel routes live only in the folder platform/admin of the API modules, and that code may not import the company tables, only the staff functions. A route marked the wrong way stops the start of the API. apps/api/eslint.config.js, RouteBoundaryCheck
Configuration is validated at start A missing or malformed setting stops the API and the worker with an error that names the variable. config.ts, in apps/api/src/core/config
Secrets never enter the repository .env is ignored by git. .env.example is the versioned list of settings, with local values only. .gitignore, .env.example
Constraint Detail
One repository, one team Every application and package lives in the same monorepo and is released together. There are no separately versioned services.
English in the product, the code and the history Code, table names, commit messages, the interface and the product texts are in English. The product interface is also translated to Spanish.
The same checks for every change Format, lint, typecheck, tests and build, then the end-to-end suite. The steps are the ones of scripts/check.sh and of .github/workflows/ci.yml.
Isolation is tested in every module The test suite of a module includes cases that prove one company cannot read or change the data of another.
A data change starts with a data design Tables, columns, indexes, expected queries and estimated volume are written and reviewed before the migration. Critical queries have their execution plan checked against a seed of realistic volume (pnpm --filter @ochema/db seed:volume and explain:volume).
No paid account to develop or test Every outside provider has a local stand-in, and the default configuration uses it. See ADR-0013.
Decisions are written down An architecture decision becomes an ADR, and this documentation changes with the code. See ADR-0020.

Ochema is used by motor carriers regulated by the Federal Motor Carrier Safety Administration (FMCSA). The product does not replace the legal judgment of a carrier, and it says so: compliance rules are a regulatory preview until the platform team marks each one validated (ADR-0019).

Area What constrains the design Where it shows in the product
Driver qualification 49 CFR Part 391. The rules of the compliance catalog and the texts of the full application cite its sections, for example 391.21 (employment application), 391.23 (investigations and safety performance history) and 391.51 (driver qualification file). Compliance > Driver files, Rules, Screenings; the full application
Drug and alcohol testing 49 CFR Parts 382 and 40. Records are confidential, so they are kept in a separate vault with their own permissions and access log. Compliance > Drug and alcohol. See ADR-0016.
Safety performance history 49 CFR 391.23: a previous employer is asked, with the driver’s signed authorization, and attempts and deadlines are recorded. Compliance > Screenings, tab Previous employers; the page a previous employer answers on
Text messages Consent per channel is recorded with the text the person saw. STOP keywords are honoured at once. Automatic messages wait for the allowed hours of the recipient. Phone carriers in the United States require each sender to register (A2P 10DLC); the platform panel records the situation of each company. Messaging
Email Automatic email carries an unsubscribe link and the one-click unsubscribe header (RFC 8058). Messaging
Personal data Social Security number, date of birth and license number are encrypted per column and masked by default. Every reveal is logged with the person who asked. Sensitive data
Electronic signature Signatures are produced by the product itself. Each envelope keeps the frozen content with its hash, the history of events and proof pages with the time and the IP address of each signer. ADR-0014
Records for an audit Registers and compliance documents are archived, never deleted, and a driver file can be exported as one package. Compliance > Audit export

The table describes what the product does. It is not a statement of legal compliance: the state of each regulatory requirement, with its evidence, is in Quality requirements, and what the product does not cover is in Risks and known limitations.

  • Solution strategy: the choices made inside these limits.
  • Glossary: CDL, DQF, FMCSA, Clearinghouse, 49 CFR and the other terms.