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.