alla-allaos-fullstack/docs/adr/0009-approved-document-storage-lifecycle.md

Status: accepted

Context: Task H introduced server-side PDF generation for quotation preview, download, and approved-document persistence. Task H.1 validated the full path with a real quotation fixture and confirmed that approved artifacts originally persisted to local disk under public/generated/.... Task I introduces a storage-provider abstraction and a database-backed document artifact model so approved PDFs are no longer tied to raw public paths as the source of truth.

Decision:

• Use a storage provider abstraction for approved quotation PDFs.
• Support a local provider for development and an S3 / MinIO-compatible provider for production-oriented deployments.
• Persist approved-document metadata in crm_document_artifacts.
• Persist approved_artifact_id on the quotation row as the primary approved-artifact reference.
• Keep approved_pdf_url as a compatibility field and allow artifact:<artifactId> references during the migration period.
• Lock approved PDF artifacts after generation and treat them as immutable-first records.

Consequences:

• Approved PDF persistence no longer depends on raw public/generated/... paths as the system of record.
• Secure download routes can resolve artifacts from database metadata and storage-provider reads.
• Local storage remains acceptable for development, but production-oriented deployments can move to S3/MinIO-compatible object storage without changing the quotation flow contract.
• Legacy approved PDFs stored under public/generated/... still require explicit migration and remain a temporary compatibility burden.

Future:

• migrate legacy approved PDFs into crm_document_artifacts
• extend the storage abstraction to manual attachments as well as generated artifacts
• support signed URLs or another private delivery strategy where required
• define operator-facing void/replacement workflow for immutable approved artifacts
• add retention/cleanup policy for superseded or voided artifacts
• move approved-PDF generation to an async job when post-approval auto-generation is introduced