Skip to content

Archiving instead of deleting

This page explains what happens when a user removes a record. It is part of section 9 of the arc42 template. The decision is recorded in ADR-0011, which replaced the first rule, ADR-0021.

A register is referenced by history. A vehicle that leaves the fleet is still named in audit rows; a job that closes still owns its applications; a document type that is retired still explains the documents collected under it. Deleting the row would either fail on those references or take history with it, and a deletion by mistake could not be undone by the user who made it.

  • A register is never deleted. It is archived, and it can be reactivated, with the two exceptions listed under Known limits.
  • An archived record leaves the default lists and the pickers, cannot be edited, and stays readable wherever history points to it.
  • The rule holds in the database: the role the application connects with cannot delete a register, whatever the code asks.
Part What it does
The column A register has archived_at, null while the record is active. 22 tables carry it today, declared in packages/db/src/schema.
The privilege The application role, ochema_app, has no DELETE on these tables. A DELETE statement fails with a permission error of PostgreSQL. The privileges are set by the migration 0007_wave01_security.sql and by the security migration of each later area, in packages/db/migrations.
The writer RegisterWriter has create, update, archive and reactivate, and no delete. Editing an archived record answers 409 record_archived; archiving twice answers the same; reactivating an active record answers 409 record_not_archived. Each operation records an audit row, <entity>.archived or <entity>.reactivated, with the value before and after. In apps/api/src/core/registers/write.ts.
The routes POST /<register>/{id}/archive and POST /<register>/{id}/reactivate, built from one pair of route decorators shared by every register, in apps/api/src/core/registers/routes.ts. The API has 21 archive routes and 19 reactivate routes today.
The lists The default list returns active rows only. The “Archived” view returns the others, newest archive first. In apps/api/src/core/registers/list.ts.
Uniqueness A label chosen by the company, such as the unit number of a vehicle, is unique among active rows only, through a partial unique index (for example vehicles_tenant_unit_key). An archived record keeps its label without blocking a new one. Reactivating a record whose label was taken meanwhile answers 409 duplicate_value.

The tables with archived_at are: application_reasons, automation_rules, campaigns, candidates, compliance_document_types, contract_templates, customers, interview_types, job_screening_questions, jobs, locations, message_templates, offer_templates, onboarding_templates, people, person_credentials, pipeline_stages, scorecard_templates, sequences, terminals, tracked_links and vehicles.

In the office system, the action is the “Archive” button of a record, the “Archived” view of its list and the “Reactivate” button. The confirmation says what will happen: the record leaves the lists and pickers, and nothing is deleted. The same screens are described for users in Record states.

Archiving is the rule for registers. Other kinds of rows follow other rules, each one deliberate. The API has 12 DELETE operations among its 535.

Kind of row What happens
A line of a form inside another register Deleted, and the change is recorded in the audit log. Examples: the contacts of a customer (customer_contacts), the tasks of an onboarding template, the fields of a contract template.
A small working item Deleted. Examples: a note on a candidate, a saved smart list, a time off entry, a place on the interview waitlist.
Access control Deleted. Examples: a custom role, the membership of a user removed from the company, a session, a calendar connection.
Transient data Purged by a routine of the worker: application drafts past their expiry, expired sessions and expired password reset tokens.
Records under a retention rule Stricter than archiving: they cannot be deleted or, once final, changed. A drug and alcohol record cannot be deleted; a wrong one is voided and recorded again. A completed signing envelope cannot be changed. The driver file of a terminated driver becomes read only until the end of its retention.
The audit log Append only: the application role can insert rows and can neither change nor delete them. See Audit log.
Guarantee Enforced by
The application role cannot delete a register. packages/db/test/isolation-wave01.test.ts, “DELETE is not allowed at all (archive instead)”, runs a DELETE on each register table as the application role and expects the permission error. The isolation test of each later area lists the exact privileges of every table, for example “ochema_app deletes form rows only” in packages/db/test/isolation-wave04-compliance.test.ts.
An edit cannot archive or reactivate by setting the column. apps/api/test/register-pattern.test.ts, “archivedAt cannot be set by an edit”.
Archiving and reactivating are audited. Every write route fails when it records no audit row. See Audit log.
A drug and alcohol record cannot be deleted. packages/db/test/wave04-drug-alcohol.test.ts, “a result is never edited and a record never deleted”.
Audit rows cannot be changed or deleted. packages/db/test/isolation.test.ts.
Expired drafts are purged, and only those. apps/api/test/application-drafts-purge.test.ts.
  • The product has no function that erases a register for good. Permanent removal of a record is a database administration task outside the product. The retention screens (Compliance > Audit export, tab “Retention”) let a company mark a file “for deletion” after its retention ended; the mark is a decision on record and erases nothing.
  • Every query decides about archived rows. Lists, counts, pickers and uniqueness each state whether archived rows take part. The register pattern makes the default safe, and a query written outside it must make the choice itself.
  • Archiving does not cascade. Archiving a terminal or a job changes that row only: a published job is taken off the careers page, and its applications stay as they are. Where an archived parent would leave its children without a valid state, the route refuses instead: archiving a pipeline stage that has applications answers 409 stage_in_use.
  • Two registers have no way back. A reason (application_reasons) and a credential of a person (person_credentials) can be archived, and the API has no reactivate route for them.
  • Archived data still occupies storage and still counts as data held. See Quality requirements.