What is soft delete and why soft delete ?

Soft delete means:

Do not remove the row from Postgres.
Only mark it as deleted.
Then hide it from normal UI/API queries.

Insurance systems usually should not physically remove audit/history records immediately.

Correct Behaviour Matrix

Case 1:
User uploads same active PDF again
→ Return existing document/run
→ Show: "This document already exists."

Case 2:
User soft-deleted PDF, then uploads same PDF again
→ Restore existing document
→ Return existing latest run
→ Show: "Document restored."

Case 3:
User uploads same filename but different content
→ Create new document/run

Case 4:
User uploads same content with different filename
→ Detect duplicate by hash
→ Return/restore existing document

Why Case 3 is required ? Why can’t we just rename the file ? Why filename should not decide duplicate

Many users download/upload files with generic names:

claim.pdf
document.pdf
scan.pdf
form.pdf
invoice.pdf

Two different claim documents can easily have the same filename:

claim.pdf  → Ritika accident claim
claim.pdf  → Rahul theft claim

If you block by filename, your app may wrongly stop a valid upload.

Also, your local storage already avoids actual file collision because uploaded PDFs are saved with:

`${Date.now()}-${safeName}`

So two claim.pdf files will not overwrite each other in apps/web/uploads.

What needs to be implemented ?

Upload is idempotent by sourceType ( PDF , EMAIL_TEXT , IMAGE ) + 
contentHash. ( if the content is same hash will be same )

How did we implement soft delete ?

Updated upload response type

Your upload endpoint should now return one of three shapes: