Clinical storage

How clinical documents are kept, verified and backed up, and how to replay a stalled copy.

Every clinical document — a treatment-plan PDF, an acceptance signature, a filed letter — is an encrypted object in your practice's cell bucket plus a second copy in a separate backup account. The record of both lives in the database, so nothing is ever read from a bucket that the record does not know about.

What happens on every upload

The database rows are written first: the document, its metadata and a copy-work row that says "primary not yet verified".
The object is written under a key derived for your practice alone.
The API reads the object back and, only when the digest matches, seals the primary copy as verified and opens the row for the backup copier.
The copier in the backup account picks the row up, copies the object, reads it back and reports the verified backup copy.

A document is read through a one-minute link the API signs for the person who was authorised. The bucket is never exposed.

The review page

Settings → Data & compliance → Clinical storage opens on the Backup copies tab, which lists every copy-work row that is not complete. Each tab shows how many rows it holds; the count turns red once a row is parked.

State	Meaning	Action
Awaiting verification	The upload did not finish its read-back.	Replay reads the object back and seals it; if the object was never written the row stays and says so.
Waiting for backup	Verified; the copier has not collected it yet.	None — the copier runs every fifteen minutes.
Backup in progress	Reserved by the copier under a lease.	None.
Parked	The copier spent its attempt budget. The last error is shown.	Replay re-arms the budget and reopens the row.

Rows are never deleted from this page. Only owners and managers can replay.

Deletions

Nothing is deleted before a document's retention date. Once that date has passed — and only when the document has a verified primary and backup copy and no legal hold — a daily scan schedules its deletion, and the Deletions tab lists every deletion that is not yet complete:

State	Meaning
Requested	Scheduled; the practice copy is still in place.
In progress	The practice copy is being removed right now.
Waiting for the backup account	The practice copy is gone. The backup account removes its own copy at least 30 days after it first sees the row — its own clock, kept in the backup account, so nothing on this side can shorten it. The Backup copy column shows the earliest possible date.
On legal hold	A legal hold covers the document; the deletion pauses wherever it is and resumes when the hold is released.
Parked	Vetoed, or the attempt budget was spent. The last error says which.

Immediately before it deletes, the backup account asks this side for a claim on the row. A legal hold, a veto or another claim that landed since it read its list refuses that claim, and nothing is deleted; a hold placed while the claim is held parks the row here, so the deletion cannot complete under it.

Two independent vetoes exist:

Veto on this page parks the row. It leaves the backup account's list at once and is never resumed on its own; if the practice copy had already gone, it stays gone and the backup copy is kept. Replay re-arms a parked row.
An operator of the backup account can place a veto object beside the backup copy. The backup account never deletes while that object exists, and the row is parked here too so you can see it.

A deletion is complete — and the document shown as deleted — only when both copies are gone. Completed rows leave the table.

Key versions

Every document is encrypted under a key derived for your practice alone from the cell's master key version. The Key versions tab shows each version of your cell and its state:

State	Meaning
Active	New uploads are encrypted under this version.
Retiring	A newer version was activated. Documents still encrypted under this one are being rewritten under the new version, one by one, and their old copies are then deleted through the ordinary deletion lifecycle (they appear in the Deletions tab as Key rotation).
Retired	Nothing is encrypted under this version any more. The secret itself is kept, so a copy an older backup brings back can still be read.

Activation is an operator action, not a button: a version is activated only after its secret has been released to every cell. Nothing about a document changes during a rotation — it stays readable throughout, and its record is never rewritten.

The Key rotations tab lists only rotations that spent their attempt budget, with the last error; Replay re-arms one and it resumes from the step it stopped in. Rotations in progress need nobody and are not listed.

Restored objects

After a restore from a database backup, the backup bucket can hold objects the restored database does not know: documents filed after the backup was taken, or copies made by a key rotation after it. The restore copies every object back into your practice bucket — except one whose practice copy a deletion had already removed, which stays with the backup account's own schedule — and files what it can from the object's own metadata. Whatever it cannot file by itself appears in the Restored objects tab, with the reason and the owner, kind, size and title read from the metadata:

Reason	What happened
A record does not exist	The patient, account or staff record the object names is not in the restored database. No row was written.
Metadata incomplete	The object carries no usable retention date, jurisdiction or type.

Two actions exist, and only these two:

Attach — choose the owner kind, enter the record's id and click Attach. The object is read back under your practice's key, its document, copy and copy-work rows are written, a patient gets its patient document, and the backup copier makes the backup copy through the ordinary lifecycle. If the object was encrypted under a retired key version, that version is reopened until the rotation has moved the object off it.
Discard — enter the reason and click Discard. Nothing is deleted: the object is filed as an organisation document of kind restore orphan, so retention, the backup account's thirty-day delay and both vetoes apply exactly as for any other document.

Documents the restore reconstructed on its own appear in the Review queue instead (source clinical-restore), naming what the metadata could not carry — the appointment, the taken-on date and tags of a patient document, or the patient link of an account document — for you to re-file by hand; once that is done, Resolve the item there. The queue's Discard refuses every restored object, and its Resolve refuses an object that has no record yet: those are attached or discarded from this page.

A cell whose vault does not carry its clinical master key refuses every clinical upload with a clear error instead of falling back to another bucket. Documents are unrecoverable without that key, which is why it is escrowed in the backup account as well.