Skip to content

ADR-0011: Archive instead of delete

  • Status: Accepted
  • Date: 2026-11-12

Registers (terminals, people, vehicles, customers, locations, jobs, candidates, document types and the ones that follow) are referenced by history: applications, stage changes, audit rows, compliance documents. The first data rule, ADR-0021, deleted rows for real everywhere except compliance documents. When the common register pattern was defined, that rule conflicted with keeping history readable and with undoing a mistake.

What happens when a user removes a register?

  • History that points to a register stays valid and readable.
  • Removing something by mistake can be undone by the user.
  • The rule must hold in the database, not only in the screens.
  1. Archive: the row stays, marked with archived_at, and can be reactivated.
  2. Hard delete, with logical deletion only where a retention rule requires it. The original rule, ADR-0021.

Chosen option: 1. It replaces ADR-0021.

A register has the column archived_at. The default list shows only active rows, the “Archived” view shows the rest, and “Reactivate” returns a row to the lists. The application role has no DELETE privilege on these tables, so no route can delete a register even by mistake. Archiving and reactivating go through the common register writer, which records an audit row with the change. Two registers are archived without a way back in the API: a reason (application_reasons) and a credential of a person (person_credentials) have an archive route and no reactivate route.

Exceptions:

  • Form lines inside another register, such as the contacts of a customer (customer_contacts), are deleted for real, with the values before and after in the audit log.
  • Access control rows are deleted for real: a custom role that is deleted, the membership of a user removed from the company, and sessions.
  • Transient data is purged: expired sessions, and application drafts past their expiry.
  • Records under a retention rule are stricter than archiving: compliance documents are kept, a completed signing envelope cannot be changed, and drug and alcohol records cannot be deleted (a wrong result is voided and recorded again).
  • Good, because a link from history to a register never breaks.
  • Good, because an archived register can be brought back with one action, except the two named above.
  • Bad, because uniqueness has to be defined over non-archived rows (for example one active vehicle per plate and state), which makes those rules partial indexes.
  • Bad, because every list, count and option query must decide whether archived rows take part.
  • Bad, because the product has no function that erases a register for good. Permanent removal is a database administration task outside the product.
  • apps/api/src/core/registers/write.ts: the register writer (create, update, archive, reactivate, audit).
  • packages/db/migrations/0007_wave01_security.sql: the privileges of the application role, without DELETE on registers.
  • Concept pages: Archiving, Audit log.