OPENKNITv0.2.0Builder
All catalogue entries

07 / 07 Module catalogue detail

Documents module

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

Browse category: AI & data

Open the builder Browse all modules

Choose the modules you want after opening the builder.

01 / Module overview

What this module does

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

Documented 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

Configuration highlights

  • Default storage adapter under bitecode.document.storage.default-storage-type

  • Local filesystem storage base path or S3-compatible bucket settings

  • Document metadata persistence in the dedicated document schema

02 / Implementation record

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, stage each multipart upload to a temporary file while computing its checksum, derive stored filename, store the file through the configured adapter, persist metadata, and remove the temporary file.
    • 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, then stream binary content from the matching adapter to the HTTP response without materializing the full document in heap.
    • 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.

Core flow source: backend/modules/document/AGENTS.md

Continue exploring

Identity modulePaymentWallet