Documents module

Document storage and retrieval module with pluggable adapters, owner scoping, metadata persistence, and admin document management.

Generate with OpenKnitBrowse other modules

What this module does

Upload, store, list, download, and delete user-owned documents.

Key capabilities

  • Upload documents with metadata persistence and checksum tracking
  • Owner-scoped list, details, download, and delete flows
  • Pluggable local or S3-compatible storage adapters with admin oversight

Core flows

  1. Upload document

    • Trigger: authenticated user or admin sends multipart upload to /documents or /admin/documents.
    • Steps: resolve current user UUID, validate files, create document UUID, compute checksum, derive stored filename, store binary content through the configured adapter, persist metadata row.
    • Output: persisted DocumentDetails records for uploaded files.
    • Failure/edge cases: missing filename, empty file payload, missing storage adapter configuration, storage write failure, DB save failure after storage write triggers cleanup.

  2. List user documents

    • Trigger: authenticated request to /documents.
    • Steps: resolve current user UUID, query only rows owned by that user, map entities to API DTOs.
    • Output: paged list of caller-owned documents.
    • Failure/edge cases: none beyond auth and pagination validation.

  3. Read or download document

    • Trigger: authenticated request to /documents/{documentId} or /documents/{documentId}/download, or admin request to /admin/documents/{documentId} or /admin/documents/{documentId}/download.
    • Steps: resolve owner scope if needed, load metadata row, optionally load binary content through the matching adapter, return metadata or file response.
    • Output: DocumentDetails metadata or binary file content with inline PDF support.
    • Failure/edge cases: user access to another user's document returns 404, missing document returns 404, storage read failure aborts download.

  4. Admin list and delete documents

    • Trigger: admin request to /admin/documents or /admin/documents/{documentId}.
    • Steps: query all documents for listing; on delete load metadata, remove binary content through the matching adapter, delete metadata row.
    • Output: paged list of all documents or successful deletion.
    • Failure/edge cases: deleting unknown document returns 404, adapter mismatch or storage delete failure aborts metadata deletion.

  5. User delete own document

    • Trigger: authenticated request to /documents/{documentId}.
    • Steps: resolve current user UUID, load row by document UUID and owner UUID, remove binary content, delete metadata row.
    • Output: successful deletion of caller-owned document.
    • Failure/edge cases: deleting another user's document returns 404.

Module is included in

  • This module is currently available only as an individual module selection.

Source paths

  • backend/modules/document
  • frontend/modules/document