jobtrackingapp/docs/architecture/attachment-storage.md

Attachment storage invariants

Updated: 2026-08-02

Attachments remain local files under Data:AttachmentsRoot/<jobId>/ with metadata in Attachments. No object-store abstraction or schema migration is used.

Invariants

• Every managed path resolves beneath Data:AttachmentsRoot without crossing a symlink/junction.
• Stored filenames are generated and stable. Renaming changes only the user-visible FileName metadata.
• A committed row normally has its final file. A temporary suffix is the only recognized recoverable exception.
• Unknown plain files are reported and preserved; reconciliation never guesses that a legacy orphan is safe to delete.
• All row lookups remain parent/job tenant-scoped.

Durable filesystem states

State	Meaning	Startup action
<final>.uploading and matching DB row	metadata committed; promotion was interrupted	atomically promote to <final>
<final>.uploading without DB row	copy/request failed before commit	purge the staging file
<final>.deleting and matching DB row	delete stopped before DB commit	restore to <final>
<final>.deleting without DB row	DB deletion committed; purge was interrupted	purge the quarantined file
plain file without DB row	unknown/legacy orphan	report only
DB row without final or recognized state	missing bytes	report only

Upload validates the complete batch before copying, stages every file, commits all metadata and derived flags in one database transaction, then promotes files. A post-commit promotion failure returns 202 and leaves .uploading for startup recovery.

Delete first atomically renames bytes to .deleting, removes metadata and updates flags in one transaction, then purges. A database failure restores the file. A post-commit purge failure returns 202 and leaves a retryable marker.

Operations

Reconciliation runs once after database initialization and before the API begins serving. It logs counts only—never file contents or paths. Nonzero missing, unsafe, unknown-orphan or failure counts require operator review. Persistent suffix-state failures are retried on the next safe service restart.

Rollback requires draining/reconciling .uploading and .deleting markers before reverting the application. Do not delete unknown plain files. The same managed-root and quarantine conventions must be reused by account deletion (SEC-009).

Object storage, content deduplication, periodic multi-replica reconciliation and destructive legacy-orphan cleanup are explicitly deferred until deployment topology or measured volume requires them.