Skip to content

Quality requirements

This page lists the non-functional requirements of the product. It is section 10 of the arc42 template. The five quality goals that shape the architecture, and their order of precedence, are in Introduction and goals; this page is the detailed list behind them.

Each attribute has one table. A row is one requirement: what is required, how the system meets it, the evidence, and the state.

State Meaning
Met Enforced by the code and proven by a test. The evidence names the test, or the check that enforces the rule.
Measured A measurement exists. The number is given with the conditions it was taken in.
Target A goal that is not reached yet: what it asks for is not built or not measured. No number is given.
Not verified Built, but not checked under real conditions.

Evidence is a file of the repository: a test, a script that reproduces a measurement, or the source that enforces the rule. Test paths are shortened to the file name where the folder is stated once: tests of the API are in apps/api/test, tests of the database in packages/db/test, and end to end scenarios in e2e/tests.

Every measurement on this page was taken on a development machine, with PostgreSQL 18 and Redis running in local containers. None was taken on production hardware, because the production environment is Proposed (see the Deployment view). Query times are the execution time of the SQL statement in the database, read from EXPLAIN (ANALYZE), with a warm cache, connected as the application role with a company in context. They are not the time a user waits for a screen.

Name used below What it is
Full volume seed The database made by pnpm --filter @ochema/db seed:volume at scale 1: 1,000 companies, 3.48 million candidates, 4.18 million applications, 7.8 million stage changes and 6 million audit rows. The largest company has 150,000 candidates. PostgreSQL ran with the memory settings of the container image. When the numbers were taken, the rows of each company were stored close together, which favours the queries over Candidates.
Quarter volume seed The same seed at scale 0.25: 1,000 companies. The largest company has 33,277 conversations and 750,000 messages, and 1,861 driver files with 57,691 compliance items. PostgreSQL ran with enlarged memory settings.
Requirement How it is met Evidence State
A company never reads or changes the data of another, even when application code forgets a filter. Row level security is enabled and forced on every table, and the application role cannot bypass it. See Tenant isolation. privileges.test.ts and the nine isolation*.test.ts files of the database; isolation.test.ts of the API Met
Paths without a session reach only the company their public identifier belongs to. Definer functions find the company from a link, a token or a key and return only ids. public-context.test.ts, wave04-public-functions.test.ts Met
Every route states who may call it. A route without an access declaration stops the API from starting. Each role gets exactly its permissions. See Authentication and permissions. route-boundary.test.ts, role-access.test.ts Met
A session cannot be read by a script or used from another site. An opaque token in an httpOnly cookie, with the __Host- prefix over HTTPS, and a cross-site request check. security.test.ts, auth.test.ts Met
Passwords are stored as slow hashes and sign-in attempts are limited. argon2id, a minimum of 10 characters, and limits per email and per address. apps/api/src/modules/platform/auth/passwords.ts, login-limit.test.ts, auth.test.ts Met
A public link reveals nothing when the database is read. Only the SHA-256 of a token is stored; expired and revoked links resolve to nothing. wave04-public-functions.test.ts, wave03-public-functions.test.ts Met
The platform team is a separate identity. Its own table, session and cookie; company routes refuse a panel session and the reverse. route-boundary.test.ts, staff-boundary.test.ts Met
An uploaded file is what it claims to be and is never public. The type is checked by the first bytes, sizes are limited, and the API serves the bytes after an access check. See Files and vaults. files.test.ts Met
A webhook is accepted only from its provider. The signature of each provider is verified. twilio-signature.test.ts, ses-webhook.test.ts Met
Sign-in can require a second factor or the single sign-on of the company. Planned. Sign-in is by email and password today. See the capability map. None Target
The production environment is assessed by a party outside the development team before the first customer uses it, and later certified. Production is Proposed. A security certification is Planned. None Target
Requirement How it is met Evidence State
Social Security number, date of birth and license number are unreadable at rest. Each value is encrypted with AES-256-GCM before it is written. See Sensitive data. sensitive.test.ts Met
A sensitive value is shown only to a person allowed to see it, and each reveal is recorded. Answers carry a masked value. Revealing needs a permission and writes a log row without the value. sensitive.test.ts Met
A sensitive value never appears in an error or in a log. Fields named as sensitive columns are removed before an error is answered or logged. sensitive.test.ts Met
Drug and alcohol results reach only the people with that permission. The rows do not exist for a session without the permission, in any query of any module, nor for the worker or a public link. wave04-drug-alcohol.test.ts, drug-alcohol.test.ts Met
Every read of a stored document is recorded. The file service writes one access row per read. files.test.ts Met
A consent is kept with the exact text the person saw. Each consent row points to a version of the consent text, which is never edited. lead-intake.test.ts, import-consent.test.ts Met
A connected calendar reveals only when the recruiter is busy. The adapters read start and end, never the title or the participants. calendar-adapters.test.ts Met
Data is encrypted in transit and, in the database and the file storage, at rest. Over HTTPS the cookies are Secure and the API sends HSTS. Encryption of the database and of the bucket depends on the production environment. security.test.ts for the first part Target
The encryption key of sensitive data can be replaced without interrupting the service. Planned. A stored value starts with a version byte, so a later format can say which key it was written with. apps/api/src/core/sensitive/sensitive.ts for the format Target
A person can ask for their data to be exported or erased. The product has no function for either. Registers are archived, never erased. See Archiving. None Target

Ochema helps a carrier keep its files in order. It does not replace the carrier’s own judgment or legal advice. See Risks and known limitations.

Requirement How it is met Evidence State
Every compliance rule states the regulation it comes from and whether it was validated. Each rule of the catalog carries its citation and a validation state, shown as “Regulatory preview” until the platform team validates it. See ADR-0019. compliance-rules.test.ts, admin-panel.test.ts Met
The rules of the catalog are correct against the current regulation. The 20 rules ship as a preview. None is validated in the catalog as it ships. packages/db/migrations/0009_wave01_catalog.sql, 0048_wave04_compliance_catalog.sql Not verified
A driver is eligible only when every required item is in order. One engine computes eligibility inside every transaction that changes an item, and once a day for dates. See Lifecycles. compliance-engine.test.ts Met
No SMS reaches a person who did not consent or who opted out, or outside the allowed hours. One send path refuses first: consent, opt-out keywords, the sending window of the company, never wider than 8 AM to 9 PM in the time zone of the recipient, and a daily cap of automatic SMS. See Messaging. messaging-send.test.ts, messaging-inbound.test.ts, messaging-time.test.ts Met
Every automatic email can be unsubscribed from, and a bounced or complained address is not written to again. A footer link per email, and suppression per company. unsubscribe.test.ts, ses-webhook.test.ts Met
A signed document cannot be changed, and each signature carries its proof. The content is frozen with its hash; proof pages record who signed, when and from where. See ADR-0014. signing.test.ts, signing-pdf.test.ts Met
The consent and legal texts shown to signers and applicants are legally reviewed. They ship as a preview, and each signature records whether its text was validated at that moment. packages/db/src/schema/compliance.ts Not verified
The drug and alcohol file is kept apart from the qualification file. A separate vault with its own permissions, access log and retention by type of record. See ADR-0016. wave04-drug-alcohol.test.ts Met
Previous employers are asked for the safety performance history, with the driver’s authorization. A request per employer of the three years before the application, refused without the signed authorization, with a 30 day deadline. safety-history.test.ts Met
A driver file can be handed to an auditor. An export as PDF, with the documents and the history, that never contains the drug and alcohol file. audit-export.test.ts Met
SMS is sent only from a number registered with the mobile carriers for business messaging. With a real provider, the send path holds SMS until the registration of the company is marked approved. The registration itself is done outside Ochema, and no real provider account has been used. apps/api/src/modules/platform-messaging/message-send.service.ts Not verified
Requirement How it is met Evidence State
A new applicant gets the first SMS within 60 seconds. The “First response” automation runs on a priority lane of the event dispatcher and of the send queue. 95th percentile of 10.4 s from the application to the SMS marked sent, over 20 applications, with the real worker and the SMS simulator. first-response-timing.test.ts, which fails above 60 s Measured
A domain event reaches its consumers within 5 seconds. An outbox read by a dispatcher with two lanes. 95th percentile of 0.97 s on the priority lane and 1.96 s on the default lane, with an idle worker. domain-events.test.ts, which fails above 5 s Measured
A list or a search answers within 100 ms of database time for Candidates and the global search, and 50 ms for the other registers. Indexes in the order of each list, and search functions that return ids. On the full volume seed, 367 queries were measured and none passed its limit. In the largest company: first page of Candidates 1.9 ms; search for a common name 8.2 ms; global search 2.0 to 21.6 ms; stage counts of the pipeline 40.4 ms, for a limit of 50 ms. One case is known to pass the limit when the rows of a company are spread across the table: a very common search term together with a second filter in Candidates, measured at 142 to 150 ms. packages/db/scripts/explain-wave01.ts (explain:wave01), volume-plans.test.ts Measured
The inbox answers within 300 ms of database time, and a conversation within 200 ms. Indexes by assignee and by conversation over monthly partitions. On the quarter volume seed, the slowest of the measured queries, the “All” view of the inbox, took 4.6 ms. apps/api/src/modules/recruit/inbox/inbox.service.ts (the SQL measured) Measured
The lists of driver files, the compliance overview and expirations answer within 300 ms of database time. Indexes by company and status. On the quarter volume seed, the largest median was 35.0 ms. The machine was shared with another test run. packages/db/scripts/explain-wave04.ts (explain:wave04) Measured
An analytics panel answers within 300 ms of database time. Panels read by period. With 500,000 applications in one company, the pipeline panels took 14 to 191 ms for periods up to 365 days, and the slowest communication panel 126 ms for 90 days. Two panels that passed the limit at 365 days read at most the last 92 days of the period, and the screen says so. apps/api/src/modules/recruit/analytics/analytics.controller.ts Measured
A spreadsheet of 10,000 candidates is imported in the background. The worker imports row by row through the same intake as every other lead. 10,000 rows took 122 s, 11.8 ms per row, with enlarged memory settings in PostgreSQL. import-volume.test.ts with IMPORT_VOLUME_ROWS=10000 Measured
A screen is ready quickly in the browser of a user. Static front ends and cursor paged lists. No measurement in a browser exists. None Target
The API keeps its response times with many users at once. No load test exists. None Not verified
Requirement How it is met Evidence State
The data model holds with many companies and one very large one. The critical queries keep their plan and their limit on the full volume seed, described above. packages/db/scripts/seed-volume.ts, explain-wave01.ts Measured
The tables that grow fastest stay manageable. The two audit logs, messages, domain events and the file access log are partitioned by month. A routine creates the partitions ahead, and the health check fails when fewer than two partitions of the audit logs are ahead. See ADR-0028. audit-partitions.test.ts, apps/api/src/modules/platform/health/health.controller.ts Met
Simultaneous requests end in a correct state. Locks and unique rules in the database. 200 simultaneous bookings of one time give one interview and 199 refusals; 300 simultaneous leads among three recruiters give 100 each. scheduling-concurrency.test.ts, lead-distribution-concurrency.test.ts Met
A large broadcast does not delay a first contact. Priorities in the send queue. With a broadcast of 5,000 SMS in progress in the same company, the 95th percentile of the first SMS was 6.9 s. first-response-timing.test.ts, messaging-queue.test.ts Measured
The worker finds the companies with work due without reading every company. One database function returns only the ids of the companies with work due. On the quarter volume seed, with 521 companies holding pending messages, it took 6.1 ms. See ADR-0006. wave03-automation-functions.test.ts, wave03-public-functions.test.ts Measured
The API and the worker run as several instances. Sessions live in the database and request counters in Redis, which the design intends for several instances. No test runs that way. None Not verified
The production environment is sized for a known load. Production is Proposed. None Target
Requirement How it is met Evidence State
The platform can tell whether the API is healthy. GET /health checks the database, Redis and the audit partitions, and answers 503 with one issue per failed check. The container images declare it as their health check. apps/api/src/modules/platform/health/health.controller.ts, Dockerfile, errors-audit.test.ts Met
A lost database connection does not stop the service. Only the request that was using the connection fails; the next one is served. connection-loss.test.ts Met
A worker that stops in the middle of its work loses nothing. A reserved message is taken again after its reservation ends, and a domain event delivery is retried and then recorded as failed. See Background work. messaging-queue.test.ts, domain-events.test.ts Met
A provider that is down delays messages and does not lose them. A temporary failure keeps the message queued, with a growing wait, for five attempts. See Error handling. messaging-queue.test.ts Met
File storage that is down fails cleanly. An upload answers 503 and leaves no record behind. import-storage.test.ts Met
The service has an availability objective. Production is Proposed; no objective is set. None Target
Data can be restored after a loss. Backup and restore belong to the production environment. No procedure exists in the repository. None Target
Requirement How it is met Evidence State
Text is readable in the light and the dark theme. The colour tokens reach WCAG AA contrast: 4.5 to 1 for text and 3 to 1 for focus indicators. See Design system. packages/ui/test/tokens.test.ts Met
The application form can be completed with the keyboard alone. Labels, focus order and announced errors on the six steps of the public form. apply.spec.ts Met
Interactive components work with the keyboard. Dialogs, menus, selects and tabs are built on Radix primitives; the pipeline board can be operated by keyboard. packages/ui/test/components.test.tsx, pipeline-board.spec.ts Met
Motion is reduced for people who ask for it. The base stylesheet removes transitions and animations under prefers-reduced-motion. No test checks it. packages/ui/css/base.css Not verified
The pages an applicant sees work on a phone. The public pages are built and exercised at 390 pixels wide. apply.spec.ts, full-application.spec.ts, signing.spec.ts, portal.spec.ts Met
The office system works on a phone. The top bar is checked at 390 pixels. The other screens are designed for a desktop and are not checked at that width. narrow.spec.ts for the top bar Not verified
The whole product conforms to WCAG 2 level AA. No audit with an automated scanner or with a screen reader has been made. None Not verified
Requirement How it is met Evidence State
A module depends on another only through its public interface, without cycles. A lint rule rejects imports of internal files, and a test starts the API with each of six entry files imported first. See Building blocks. apps/api/eslint-module-boundary.js, lint-boundary.test.ts, module-cycles.test.ts Met
The API contract and its client cannot drift from the code. Both are generated, and tests compare them with what the code produces. See API contract. openapi.test.ts, packages/contracts/test/generated.test.ts Met
The look can be replaced without touching the screens. Lint rules reject any colour, font or size outside the design system. packages/config/test/eslint-plugin-ochema.test.js Met
The database changes only through versioned migrations that work over existing data. 53 numbered migrations, applied by a role the applications do not use, with upgrade tests over a database that already has companies. See ADR-0004. The 14 upgrade*.test.ts files, privileges.test.ts Met
A provider can be replaced by configuration. Each provider sits behind an adapter interface chosen by a setting. See ADR-0013. twilio-send.test.ts, ses-send.test.ts, smtp-send.test.ts, calendar-adapters.test.ts Met
Every change passes the same checks. Format, lint, type check, tests and build, by one script and by the continuous integration workflow. scripts/check.sh, .github/workflows/ci.yml Met
The generated pages of this documentation match the code. A test regenerates the reference pages and compares them. apps/docs/test/reference.test.ts Met
Requirement How it is met Evidence State
The whole suite runs with no provider account and no network. Simulators and local stand-ins for SMS, email, calendars and file storage. See Testing. docker-compose.yml, apps/api/test/fake-s3.ts Met
Rules of the database are tested in a real database. The database and API suites run against PostgreSQL with every migration applied, as the application role. apps/api/test/global-setup.ts, packages/db/test/global-setup.ts Met
Test files do not interfere with each other. Each file creates its own companies and uses its own Redis key prefix. Files that change shared rows run one at a time. apps/api/vitest.config.ts Met
The product is covered by automated tests at every layer. 4,015 test cases declared in 334 files of unit and integration tests, and 63 end to end scenarios in 44 files, counted in the code. See Testing. The test folders of each workspace Measured
The sample data is the same on every run. The seed is deterministic and idempotent. packages/db/test/seed.test.ts Met
The share of the code exercised by tests is known. No coverage tool is configured. None Target
The product is tested in the browsers customers use. The end to end suite runs in Chromium only. e2e/playwright.config.ts Not verified
Requirement How it is met Evidence State
A register is never deleted. Registers are archived, and the application role has no DELETE on them. See Archiving. isolation-wave01.test.ts Met
The audit log cannot be changed. The application role can insert audit rows and can neither change nor delete them. See Audit log. isolation.test.ts of the database Met
The file of a terminated driver is kept until the end of its retention. The file becomes read only and gets the end date of its retention. Nothing is deleted automatically; after that date a person decides. audit-export.test.ts Met
A drug and alcohol record is never deleted, and its retention follows the type of record. The database refuses the deletion, and each record gets its retention rule. wave04-drug-alcohol.test.ts Met
The retention periods are correct against the current regulation. The periods ship as a regulatory preview. packages/db/migrations/0048_wave04_compliance_catalog.sql, 0052_wave04_drug_alcohol_catalog.sql Not verified
Data with a short life does not accumulate. A routine purges expired application drafts, sessions and password reset tokens, and an audit export file leaves the storage after 7 days. application-drafts-purge.test.ts, audit-export.test.ts Met
Data past its retention is erased. A person can mark a file for deletion after its retention ended. The product erases nothing; permanent removal is outside it. None Target
Backups follow the same retention as the data. Backups belong to the production environment. None Target
Requirement How it is met Evidence State
A wrong configuration is found at start, not at the first request. With a real provider selected and a setting missing, the API and the worker refuse to start and name the variable. ses-send.test.ts, smtp-send.test.ts, apps/api/src/core/config/config.ts Met
A failure can be traced from the answer to the log. Every error answer carries a request id that the log line of the failure repeats. See Error handling. errors-audit.test.ts Met
A missing encryption key never leads to data stored in clear. The routes that write or reveal sensitive data answer 503 and write nothing. sensitive.test.ts Met
Routine maintenance runs by itself. The worker creates partitions ahead and purges expired data on a schedule. audit-partitions.test.ts, application-drafts-purge.test.ts Met
What the platform team does is recorded. Each function of the platform panel checks the session of the team member in the database and writes to a separate audit log. See ADR-0023. staff-audit.test.ts, admin-panel.test.ts Met
The services are packaged as container images. Three images, for the API, the worker and the careers server, that run as a non-root user and are built by the continuous integration workflow. Dockerfile, .github/workflows/ci.yml Met
Messages are sent through real provider accounts. The adapters exist and are tested against local stand-ins. None Not verified
The production environment has a release pipeline, monitoring and alerting. None exists in the repository. None Target