@tstdl/base 0.93.36 → 0.93.38

package/source/document-management/CONCEPT.md

@@ -1,166 +0,0 @@
-**Konzept: Dokumentenmanagementsystem (DMS)**
-
-## Kernidee
-
-Ein zentrales System (Modul) zur Verwaltung von Dokumenten, die in logischen Gruppen, sogenannten "Collections", organisiert sind. Ziel ist es, Dokumente effizient zu erfassen, automatisch zu analysieren, korrekt zuzuordnen und ihre Qualität durch definierte Prozesse, menschliche Überprüfungen und Validierungen sicherzustellen. Künstliche Intelligenz (KI, mittels LLMs) unterstützt maßgeblich bei der Klassifizierung und Extraktion von Informationen. Jeder KI-Schritt wird durch menschliche Überprüfung und Korrektur bestätigt, bevor der nächste Prozessschritt angestoßen wird.
-
-## Hauptkonzepte und Informationen
-
-1.  **Collections**
-
-    - Dienen als thematische oder kontextbezogene Behälter (z.B. pro Projekt, Kunde, Mitarbeiterakte).
-    - **Können hierarchisch aufgebaut sein:** Eine Collection kann einer **übergeordneten Collection** zugeordnet werden, um Strukturen abzubilden (z.B. kann die Collection einer Person Unter-Collections wie 'Einkommen', 'Versicherungen' beinhalten, die alle der Haupt-Collection 'Person X' untergeordnet sind).
-    - Bilden den Rahmen für spezifische Dokumentenanforderungen und Validierungsregeln.
-    - Metadaten (z.B. Name) können hinterlegt oder aus der umgebenden Applikation bezogen werden.
-
-2.  **Dokumente**
-
-    - Repräsentieren eine Informationseinheit, basierend auf einer Datei (z.B. PDF, Bild).
-    - Enthalten KI-extraierte und manuell geprüfte/korrigierte Metadaten (Titel, Datum, Zusammenfassung, Tags).
-    - Werden einer **Dokumentenart** (z.B. "Rechnung", "Vertrag") zugeordnet (Klassifizierung), die in **Kategorien** (z.B. "Finanzen", "Recht") gruppiert ist.
-    - Speichern strukturierte **Eigenschaften** (z.B. Rechnungsnummer, Vertragsbeginn), definiert durch die Dokumentenart.
-    - Sind einer oder mehreren Collections zugeordnet.
-    - Besitzen einen **Genehmigungsstatus** (z.B. "In Analyse", "Wartet auf Prüfung", "Genehmigt"). Nach finaler Genehmigung ("Approved") ist das Dokument **unveränderlich**. Notwendige Änderungen erfordern das Archivieren des alten und Hochladen eines neuen Dokuments.
-    - Können direkt zur Erfüllung einer offenen **Dokumentenanforderung** dienen.
-
-**3. Dokument-Collection-Zuordnung**
-
-Die Verknüpfung eines Dokuments mit einer oder mehreren Collections ist ein zentrales Element des Systems. Es gibt zwei primäre Wege, wie diese Zuordnung zustande kommen kann:
-
-- **Direkte Zuordnung:**
-
-  - Ein Dokument kann _direkt_ einer oder mehreren Collections zugewiesen werden. Dies kann beispielsweise beim initialen Upload geschehen, wenn der Nutzer explizit Ziel-Collections angibt, oder durch eine spätere manuelle Zuweisung durch einen Bearbeiter (z.B. für Dokumente, die ohne spezifische Anforderung eingingen).
-  - Diese direkte Verbindung wird technisch durch einen Eintrag in der Entität `DocumentCollectionAssignment` repräsentiert, die eine `documentId` mit einer `collectionId` verknüpft.
-
-- **Zuordnung durch Erfüllung einer Dokumentenanforderung:**
-  - Eine `DocumentRequest` beschreibt den Bedarf an einem Dokument für eine oder mehrere spezifische Collections. Die Entität `DocumentAssignmentCollectionTarget` legt fest, welche Collections (`collectionId`) für eine bestimmte Anforderung (`requestId`) relevant sind.
-  - Wenn ein Dokument hochgeladen oder ausgewählt und **akzeptiert** wird, um _diese spezifische Anforderung zu erfüllen_ (typischerweise nach Abschluss der Prüfungs- und Genehmigungsschritte für das Dokument), wird die Verbindung zwischen dem Dokument und den relevanten Collections hergestellt.
-  - **Konkret bedeutet dies:** Das System erstellt für jede `collectionId`, die über `DocumentAssignmentCollectionTarget` mit der erfüllten `requestId` verknüpft ist, einen **neuen Eintrag in der `DocumentCollectionAssignment`-Tabelle**. Dieser Eintrag verknüpft die `documentId` des erfüllenden Dokuments mit der jeweiligen `collectionId`.
-  - Somit wird die Anforderung nicht nur als erfüllt markiert, sondern das Dokument wird auch **aktiv und direkt** den vorgesehenen Collections zugeordnet, genau wie bei einer manuellen direkten Zuordnung. Die Erfüllung der Anforderung _löst also die Erstellung der direkten `DocumentCollectionAssignment`-Zuordnung(en) aus_.
-
-**Archivierung der Zuordnung:**
-Unabhängig davon, _wie_ die Zuordnung zustande kam (direkt oder durch Erfüllung einer Anforderung), kann jede einzelne `DocumentCollectionAssignment`-Zuordnung als **"archiviert"** markiert werden. Dies bedeutet, dass das Dokument für _diese spezifische Collection_ nicht mehr aktiv relevant ist und aus Standard-Übersichten dieser Collection ausgeblendet wird. Das Dokument selbst bleibt jedoch bestehen und kann in anderen Collections, denen es zugeordnet ist (und wo die Zuordnung nicht archiviert ist), weiterhin aktiv sein.
-
-4.  **Dokumentenarten & Eigenschaften**
-
-    - **Kategorien & Arten:** Strukturieren den Dokumentenbestand fachlich. Eine Art (z.B. "Einkommensnachweis") gehört zu einer Kategorie (z.B. "Personal").
-    - **Kategorien können hierarchisch strukturiert sein:** Eine Kategorie kann einer **übergeordneten Kategorie** zugeordnet werden (z.B. könnte "Gehaltsabrechnung" eine Unterkategorie von "Einkommensnachweise" sein, welche wiederum zur übergeordneten Kategorie "Personal" gehört).
-    - **Eigenschaften:** Definieren wiederverwendbare Datenfelder mit Datentyp. Relevanten Eigenschaften werden einer Dokumentenart zugewiesen.
-
-**5. Dokumentenanforderungen**
-
-- Beschreiben den Bedarf an einem Dokument (oft einer spezifischen Art).
-- **Sind einer oder mehreren Collections zugeordnet:** Die spezifischen Collections, für die eine Anforderung gilt, werden über die Entität `DocumentAssignmentCollectionTarget` festgelegt. Ein Dokument, das diese Anforderung erfüllt, wird somit diesen Collections zugeordnet (siehe Abschnitt 3: Indirekte Zuordnung).
-- Können Kommentare/Hinweise enthalten.
-- Haben einen Status (z.B. "Offen", "Erfüllt").
-- Können über **Vorlagen** standardisiert erstellt werden.
-
-6.  **Eingehende Dokumente ohne direkte Anforderung (Zuordnungsaufgabe)**
-    - Dokumente können hochgeladen werden, ohne direkt einer Anforderung zugeordnet zu sein, aber mit Ziel-Collection(s).
-    - Sie durchlaufen die automatische Analyse (Klassifizierung/Extraktion) und die nachfolgenden menschlichen Prüfschritte.
-    - KI-unterstützt wird versucht, das Dokument einer passenden, offenen Anforderung in den Ziel-Collections zuzuordnen.
-    - **Falls keine passende Anforderung gefunden wird:** Das Dokument erscheint in einer spezifischen Benutzeroberfläche ("Unzugeordnete Dokumente"). Dort kann ein Bearbeiter es manuell einer Anforderung zuordnen, eine neue Anforderung erstellen (falls die umgebende Applikation dies erlaubt) oder das Dokument (bzw. dessen Eintrag im DMS) löschen.
-
-## Kernprozesse & Workflow (Sequenziell & Menschen-gesteuert)
-
-1.  **Dokumentenerfassung:**
-
-    - Upload mit optionaler Collection-Zuordnung oder zur Erfüllung einer Anforderung.
-    - **Dublettenprüfung:** Beim Upload wird mittels Hash/Prüfsumme geprüft, ob eine _identische Datei_ bereits in der/den Ziel-Collection(s) existiert. Bei Fund wird der Nutzer informiert (Verhalten bei Dublette definieren: z.B. Upload abbrechen, nur Metadaten verknüpfen?).
-    - Der Upload stößt **automatisch** den ersten Workflow-Schritt an: **Automatische Analyse & Anreicherung**. Dies geschieht typischerweise asynchron (siehe Technische Implementierung).
-
-2.  **Automatische Analyse & Anreicherung (KI-Schritt 1):**
-
-    - Läuft als **Hintergrundprozess** (siehe Technische Implementierung).
-    - KI (LLM) analysiert das Dokument.
-    - Bestimmt **Dokumentenart** und extrahiert **Metadaten/Eigenschaften**.
-    - Speichert die _vorläufigen_ Ergebnisse am Dokument.
-    - Dokument erhält Status "Wartet auf Prüfung (Analyse)".
-
-3.  **Menschliche Überprüfung & Korrektur (Analyse):**
-
-    - Ein Bearbeiter prüft die KI-Ergebnisse (Klassifizierung, extrahierte Daten) in der UI, sobald der Hintergrundprozess abgeschlossen ist.
-    - **Korrektur:** Bei Fehlern korrigiert der Bearbeiter die Daten _direkt_. Es gibt keinen "Ablehnen"-Schritt, der die KI erneut anstößt.
-    - Nach Prüfung/Korrektur stößt der Bearbeiter **manuell** den nächsten Schritt an (z.B. Validierung oder direkt Genehmigung).
-
-4.  **Validierung (Optionaler Schritt):**
-
-    - _Falls konfiguriert:_ Basierend auf Dokumentenart/Collection werden Regeln geprüft (Vollständigkeit, Plausibilität).
-    - Kann automatisch (ggf. als weiterer **Hintergrundprozess**) oder als menschliche Aufgabe erfolgen. Ergebnisse werden protokolliert.
-    - Dokument erhält Status "Wartet auf Prüfung (Validierung)".
-
-5.  **Menschliche Überprüfung & Korrektur (Validierung):**
-
-    - _Falls Validierungsschritt erfolgte:_ Ein Bearbeiter prüft die Validierungsergebnisse.
-    - Er entscheidet über das Vorgehen (z.B. Daten korrigieren, Warnung akzeptieren).
-    - Nach Prüfung/Korrektur stößt der Bearbeiter **manuell** den finalen Genehmigungsschritt an.
-
-6.  **Menschliche Genehmigung (Final):**
-
-    - Ein Bearbeiter führt die finale Prüfung durch.
-    - Mit der Bestätigung wird der **Genehmigungsstatus** des Dokuments auf "Genehmigt" gesetzt. Das Dokument ist ab jetzt **unveränderlich**.
-    - Falls das Dokument einer Anforderung zugeordnet ist, wird geprüft, ob die Anforderung damit als "Erfüllt" markiert werden kann (ggf. separater Bestätigungsschritt durch den Anforderer, je nach Prozessdesign).
-
-7.  **Zuordnung (für unzugeordnete Dokumente):**
-    - Parallel oder nach der Genehmigung: Wenn ein Dokument initial keiner Anforderung zugeordnet war und die KI keine passende fand, erfolgt die manuelle Zuordnung oder Löschung über die dedizierte Oberfläche (siehe Punkt 6 oben). Die KI-gestützte Suche nach passenden Anforderungen kann ebenfalls als **Hintergrundprozess** implementiert werden.
-
-## Technische Implementierungsaspekte
-
-1.  **Asynchrone Verarbeitung mittels Queues:**
-
-    - **Kernprinzip:** Zeitintensive, automatisierte Aufgaben wie die KI-Analyse (Klassifizierung, Extraktion), die potenzielle Zuordnung zu Anforderungen und ggf. automatische Validierungen werden **nicht synchron** während der Benutzerinteraktion ausgeführt.
-    - **Mechanismus:** Beim Anstoßen einer solchen Aufgabe (z.B. durch Dokumenten-Upload) wird ein **Job** in eine **Warteschlange (Queue)** eingestellt. Der Job enthält typischerweise die ID des Dokuments und die auszuführende Aufgabe.
-    - **Vorteile:**
-      - **Entkopplung & Responsivität:** Die Benutzeroberfläche (UI) oder die aufrufende API blockiert nicht, sondern kann dem Benutzer sofort Feedback geben (z.B. "Dokument wird analysiert").
-      - **Skalierbarkeit:** **Worker-Prozesse** (Consumers) können die Jobs aus der Queue unabhängig voneinander abarbeiten. Die Anzahl der Worker kann je nach Last skaliert werden (mehrere Server/Instanzen können sich die Arbeit teilen).
-      - **Robustheit:** Bei temporären Fehlern (z.B. LLM-API nicht erreichbar) können Jobs in der Queue verbleiben und später erneut versucht werden (Retry-Mechanismen).
-
-2.  **Workflow:**
-
-    - **Trigger:** Ein Ereignis (z.B. Dokumenten-Upload, manuelles Anstoßen eines optionalen Schritts) führt dazu, dass die Kernapplikation (z.B. über ein API-Backend) einen Job in die entsprechende Queue legt.
-    - **Verarbeitung:** Ein oder mehrere Worker-Prozesse überwachen die Queue. Sobald ein Job verfügbar ist, nimmt ein Worker ihn auf, führt die Aufgabe aus (z.B. Aufruf der LLM-API, Regelprüfung) und aktualisiert anschließend den Status und die Daten des Dokuments in der Datenbank.
-    - **Benutzer-Feedback:** Die UI muss den asynchronen Status reflektieren (z.B. "In Analyse"). Sobald der Worker den Status aktualisiert hat (z.B. auf "Wartet auf Prüfung (Analyse)"), wird dies in der UI sichtbar (z.B. durch Polling, WebSockets oder beim nächsten Laden der Ansicht).
-    - **Datenbank-Design** Der aktuelle Stand des Workflows wird in der separaten DocumentWorkflow Entität gespeichert. Für jeden Schritt wird hierzu eine eigene Entität erstellt.
-
-3.  **Fehlerbehandlung & Monitoring:**
-
-    - Robuste Fehlerbehandlung in den Workern ist essenziell (z.B. für den Fall, dass ein Dokument nicht analysiert werden kann).
-    - Mechanismen für Retries bei temporären Fehlern.
-
-4.  **Speicherung der Dokumentdateien in Objektspeicher (S3):**
-
-    - **Kernprinzip:** Die eigentlichen Dokumentdateien (z.B. PDFs, Bilder) werden aus Gründen der Skalierbarkeit, Kosteneffizienz und Robustheit nicht in der primären Datenbank oder auf lokalen Dateisystemen der Anwendungsserver gespeichert, sondern in einem dedizierten Objektspeicher wie bspw. S3
-    - **Mechanismus:**
-      - Das DMS speichert in seiner Datenbank _nicht_ die Datei selbst, sondern nur die Metadaten zum Dokument (siehe Punkt 2 unter "Hauptkonzepte").
-      - Beim **Upload** wird die Datei direkt in den konfigurierten S3-Bucket abgelegt, der Objekt-Key entspricht hierbei grob der ID des Dokuments.
-      - **Worker-Prozesse** (z.B. für Analyse, Validierung) greifen über die S3-API auf die Datei im Objektspeicher zu, um deren Inhalt zu lesen und zu verarbeiten.
-      - Die **Benutzeroberfläche** ruft bei Bedarf (z.B. zur Anzeige einer Dokumentenvorschau) über das Backend die Datei ebenfalls aus S3 ab (über temporär signierte URLs für direkten Browserzugriff).
-
-## Fachliche Ziele
-
-- **Effizienz:** Reduzierung manueller Dateneingabe durch KI; klare, wenn auch manuell gesteuerte, Prozessschritte, unterstützt durch nicht-blockierende Hintergrundverarbeitung.
-- **Datenqualität:** Sicherstellung korrekter Daten durch zwingende menschliche Überprüfung/Korrektur und optionale Validierungen.
-- **Compliance & Nachvollziehbarkeit:** Unveränderlichkeit genehmigter Dokumente; Protokollierung von Statuswechseln und Genehmigungen durch Benutzer.
-- **Zentralisierung & Struktur:** Zentrale Ablage mit Zugriff über hierarchische Collections und Kategorien.
-- **Skalierbarkeit der Speicherung:** Ermöglichung der Speicherung großer Mengen von Dokumentdateien ohne Beeinträchtigung der Applikationsperformance oder Datenbankgröße.
-
-## Abgrenzung & Zukünftige Erweiterungen
-
-- **Außerhalb des Scopes (Initial):**
-  - Berechtigungsmanagement (erfolgt durch umgebende Applikation; DMS muss es aber unterstützen/respektieren).
-  - Umfassende Suche & Recherche (über Metadaten hinaus).
-  - Dokumenten-Lebenszyklus-Management & Aufbewahrungsfristen.
-  - Dashboards & Reporting (erfolgt durch umgebende Applikation).
-  - Direkte Verknüpfungen zwischen Dokumenten auf DMS-Ebene (erfolgt durch umgebende Applikation).
-  - Benachrichtigungssystem.
-  - Externe APIs / Integrationen (Modul ist intern).
-- **Zukünftige Erweiterungen (Potenziell):**
-  - Fine-tuning der KI-Modelle (LLMs) basierend auf gesammelten Korrekturen.
-  - Erweiterte Suchfunktionen.
-  - Lebenszyklus-Management.
-  - Benachrichtigungen.
-
-## Protokollierung (Audit-Trail)
-
-- Alle Statusänderungen von Dokumenten und Anforderungen werden protokolliert.
-- Insbesondere wird festgehalten, **wer** (Benutzer) **wann** einen Workflow-Schritt (Prüfung, Korrektur, Genehmigung) abgeschlossen und den nächsten angestoßen hat.

package/source/document-management/README.md

@@ -1,409 +0,0 @@
-# Document Management Module
-
-This module provides a comprehensive system for managing documents within logical groups called "Collections". It facilitates efficient document capture, AI-powered analysis, correct assignment, and quality assurance through defined workflows, human reviews, and validations.
-
-## Table of Contents
-
-- [Features](#features)
-- [Core Concepts](#core-concepts)
-- [Usage](#usage)
-  - [Client-Side API Usage](#client-side-api-usage)
-    - [Initializing the API Client](#initializing-the-api-client)
-    - [Loading Collection Data](#loading-collection-data)
-    - [Uploading a Document](#uploading-a-document)
-    - [Updating a Document](#updating-a-document)
-    - [Retrieving Document Content](#retrieving-document-content)
-    - [Managing Categories and Types](#managing-categories-and-types)
-    - [Managing Document Requests](#managing-document-requests)
-    - [Advancing a Document's Workflow](#advancing-a-documents-workflow)
-  - [Server-Side Configuration](#server-side-configuration)
-    - [Module Configuration](#module-configuration)
-    - [Implementing the Authorization Service](#implementing-the-authorization-service)
-    - [Implementing the Ancillary Service](#implementing-the-ancillary-service)
-    - [Initializing Categories and Types](#initializing-categories-and-types)
-- [API Summary](#api-summary)
-
-## Features
-
-- **Document Collections**: Organize documents into logical, hierarchical groups (e.g., per user, project, or case).
-- **AI-Powered Workflow**: Automated, asynchronous workflow for document processing:
-  - **Classification**: AI automatically determines the document type.
-  - **Extraction**: AI extracts key metadata, properties, and tags from the document content.
-  - **Assignment**: AI suggests assignments to relevant collections or open document requests.
-- **Human-in-the-Loop**: Each automated workflow step is followed by a manual review stage, allowing users to verify and correct AI-generated data before proceeding.
-- **Structured Data**:
-  - **Categories & Types**: Define a hierarchical taxonomy for classifying documents (e.g., Category: "Invoices", Type: "Incoming Invoice").
-  - **Properties**: Define custom, typed data fields for different document types (e.g., "Invoice Number", "Amount").
-- **Document Requests**: Create requests for specific documents within collections, which can be fulfilled by uploading a new document.
-- **File Handling**: Secure file uploads via pre-signed URLs, storage in a configurable object storage provider, and generation of file previews (e.g., for PDFs).
-- **Real-time Updates**: Subscribe to collection data changes via Server-Sent Events (SSE) for a responsive UI.
-- **Extensible Authorization**: Fine-grained access control managed through a dedicated authorization service.
-
-## Core Concepts
-
-The document management module is built around a structured, workflow-driven approach to handling documents.
-
-### Collections
-
-A **Collection** is the primary container for organizing documents. It represents a specific context, such as a user's personal documents, a project folder, or a customer file. Collections can be hierarchical, allowing for nested structures. They serve as the scope for document requests and authorization rules.
-
-### Documents, Categories, Types, and Properties
-
-- A **Document** represents a single file (e.g., a PDF or image) and its associated metadata.
-- Every document is classified by a **Document Type** (e.g., "Invoice"), which belongs to a **Document Category** (e.g., "Finance"). This creates a structured taxonomy.
-- **Document Properties** are custom, typed data fields (e.g., "Invoice Number" as text, "Amount" as a decimal) that can be attached to document types, allowing structured data to be extracted and stored.
-
-### AI-Powered Workflow
-
-When a document is uploaded, it enters an asynchronous, queue-based workflow designed to process it without blocking the user.
-
-1.  **Classification**: The AI analyzes the document's content to determine its `DocumentType`.
-2.  **Extraction**: The AI extracts metadata (title, date, summary), suggests relevant tags, and populates the `DocumentProperties` associated with its type.
-3.  **Assignment**: If the document was not uploaded for a specific purpose, the AI attempts to assign it to the most suitable `DocumentCollection` or an open `DocumentRequest`.
-4.  **Validation**: Optional custom validation rules can be executed to check for data plausibility or completeness.
-
-After each automated step (except Classification), the workflow enters a `Review` state. A user must then verify the results, make corrections if necessary, and manually trigger the next step. Once a document is finally approved, it becomes immutable.
-
-### Document Requests
-
-A **Document Request** signifies the need for a specific type of document within one or more collections. Users can fulfill a request by uploading a new document, which then becomes directly associated with that request and its collections. **Request Templates** allow for the standardized creation of common sets of document requests.
-
-### Authorization and Ancillary Services
-
-- **`DocumentManagementAuthorizationService`**: This abstract class must be implemented by the consuming application. It defines the rules for who can perform actions like reading collections, uploading documents, or approving them.
-- **`DocumentManagementAncillaryService`**: This service allows the application to provide context-specific metadata for collections, such as a user-friendly name or a grouping identifier, which are not part of the core module's data model.
-
-## Usage
-
-### Client-Side API Usage
-
-#### Loading Collection Data
-
-You can fetch all data for one or more collections at once. The returned data includes documents, requests, categories, and more.
-
-```typescript
-import { toEnrichedDocumentManagementData } from '@tstdl/base/document-management';
-
-const userFolderId = '...';
-const carFolderId = '...';
-
-// Fetch initial data
-const data = await documentManagementApi.loadData({ collectionIds: [userFolderId, carFolderId] });
-
-// The raw data can be wrapped in an "enriched" data view for easier navigation and access
-const enrichedData = toEnrichedDocumentManagementData(data);
-console.log(enrichedData.documents);
-console.log(enrichedData.requests);
-
-// For real-time updates, use the stream endpoint
-const stream = await documentManagementApi.loadDataStream({ collectionIds: [userFolderId] });
-
-for await (const updatedData of stream) {
-  console.log('Received updated data:', updatedData);
-}
-```
-
-#### Uploading a Document
-
-Uploading a document is a two-step process: first, initiate the upload to get a secure URL, then upload the file and create the document record.
-
-```typescript
-const file = new File(['...'], 'invoice.pdf', { type: 'application/pdf' });
-
-// 1. Initiate the upload
-const { uploadId, uploadUrl } = await documentManagementApi.initiateDocumentUpload({ contentLength: file.size });
-
-// 2. Upload the file to the provided URL
-await fetch(uploadUrl, { method: 'PUT', body: file });
-
-// 3. Create the document record and start the workflow
-
-// Example 1: Assign to a specific collection
-const document = await documentManagementApi.createDocument({
-  uploadId,
-  originalFileName: file.name,
-  assignment: {
-    collections: 'user-collection-id-123'
-  }
-});
-
-// Example 2: Fulfill a specific document request
-const documentForRequest = await documentManagementApi.createDocument({
-  uploadId,
-  originalFileName: file.name,
-  assignment: {
-    request: 'request-id-456'
-  }
-});
-
-// Example 3: Automatic assignment (AI will determine the best collection/request)
-const documentForAutoAssignment = await documentManagementApi.createDocument({
-  uploadId,
-  originalFileName: file.name,
-  assignment: {
-    automatic: {
-      target: 'request', // or 'collection'
-      scope: ['user-collection-id-123', 'car-collection-id-789'] // collections to search within
-    }
-  }
-});
-
-console.log('Document created:', document.id);
-```
-
-#### Updating a Document
-
-After a document has been processed by the AI and is in the `Review` state, you can update its metadata.
-
-```typescript
-const documentId = '...';
-
-await documentManagementApi.updateDocument({
-  id: documentId,
-  title: 'Corrected Invoice Title',
-  tags: ['invoice', 'important', 'new-tag'],
-  properties: [
-    { propertyId: 'invoice-number-prop-id', value: 'INV-2024-001' },
-    { propertyId: 'amount-prop-id', value: 199.99 }
-  ],
-  collections: {
-    assign: ['another-collection-id'],
-    archive: ['old-collection-id']
-  }
-});
-```
-
-#### Retrieving Document Content
-
-You can get URLs to download the original file or a generated preview image.
-
-```typescript
-const documentId = '...';
-
-// Get a URL to view the document inline in the browser
-const viewUrl = await documentManagementApi.getContentUrl({ id: documentId });
-window.open(viewUrl, '_blank');
-
-// Get a URL to force-download the document
-const downloadUrl = await documentManagementApi.getContentUrl({ id: documentId, download: true });
-
-// Get a URL for a preview image of the first page
-const previewUrl = await documentManagementApi.getPreviewUrl({ id: documentId, page: 1 });
-```
-
-#### Managing Categories and Types
-
-If authorized, you can create new document categories and types.
-
-```typescript
-// Create a root category
-const financeCategory = await documentManagementApi.createCategory({
-  label: 'Finance',
-  parentId: null
-});
-
-// Create a type within that category
-const invoiceType = await documentManagementApi.createType({
-  label: 'Invoice',
-  categoryId: financeCategory.id
-});
-```
-
-#### Managing Document Requests
-
-You can create individual requests or apply predefined templates.
-
-```typescript
-// Create a single document request in a user's collection
-const request = await documentManagementApi.createDocumentRequest({
-  typeId: 'invoice-type-id',
-  comment: 'Please upload your latest phone bill.',
-  collectionIds: ['user-collection-id-123']
-});
-
-// Apply a template to create multiple requests at once
-await documentManagementApi.applyDocumentRequestsTemplate({
-  id: 'new-customer-template-id',
-  collectionIds: ['user-collection-id-123']
-});
-```
-
-#### Advancing a Document's Workflow
-
-When a document is in `Review` state, a user can approve the current step's data and proceed to the next.
-
-```typescript
-const documentId = '...';
-
-// After reviewing the extracted data, proceed to the assignment step
-await documentManagementApi.proceedDocumentWorkflow({ id: documentId });
-```
-
-### Server-Side Configuration
-
-#### Module Configuration
-
-To use the module, you need to configure it in your application's setup process.
-
-```typescript
-import { configureDocumentManagement } from '@tstdl/base/document-management/server';
-import { AppAuthorizationService } from './my-authorization.service.js';
-import { AppAncillaryService } from './my-ancillary.service.js';
-
-// In your bootstrap file (e.g., bootstrap.ts)
-export function bootstrap() {
-  // ... other configurations
-
-  configureDocumentManagement({
-    // Service to provide application-specific collection metadata
-    ancillaryService: AppAncillaryService,
-
-    // Service for handling all authorization checks
-    authorizationService: AppAuthorizationService,
-
-    // Names of the configured S3 Object Storage modules
-    fileObjectStorageModule: 'document-files',
-    fileUploadObjectStorageModule: 'document-uploads',
-    filePreviewObjectStorageModule: 'document-previews',
-
-    // Optional: Max file size in bytes
-    maxFileSize: 10 * 1024 * 1024, // 10 MB
-  });
-}
-```
-
-#### Implementing the Authorization Service
-
-You must provide an implementation for `DocumentManagementAuthorizationService` to control access.
-
-```typescript
-import { DocumentManagementAuthorizationService } from '@tstdl/base/document-management';
-import { Singleton } from '@tstdl/base/injector';
-import type { MyTokenPayload } from './my-token.js'; // Your application's token type
-
-@Singleton()
-export class AppAuthorizationService extends DocumentManagementAuthorizationService<MyTokenPayload> {
-  getTenantId(token?: MyTokenPayload): string {
-    if (!token?.tenantId) {
-      throw new Error('Tenant ID is required.');
-    }
-    return token.tenantId;
-  }
-
-  getSubject(token?: MyTokenPayload): string {
-    return token!.subject;
-  }
-
-  async canReadCollection(collectionId: string, token?: MyTokenPayload): Promise<boolean> {
-    // Your logic here: e.g., check if the user (token.subject) owns this collection
-    return true;
-  }
-
-  async canCreateDocuments(collectionId: string, token?: MyTokenPayload): Promise<boolean> {
-    // Your logic here
-    return true;
-  }
-
-  // ... implement all other abstract methods
-}
-```
-
-#### Implementing the Ancillary Service
-
-Implement `DocumentManagementAncillaryService` to provide display names and groups for your collections.
-
-```typescript
-import { DocumentManagementAncillaryService } from '@tstdl/base/document-management/server';
-import type { DocumentCollection, DocumentCollectionMetadata } from '@tstdl/base/document-management';
-import { inject, Singleton } from '@tstdl/base/injector';
-
-import { UserRepository } from './my-user.repository.js'; // Your application's repositories
-
-@Singleton()
-export class AppAncillaryService extends DocumentManagementAncillaryService {
-  readonly #userRepository = inject(UserRepository);
-
-  async resolveMetadata(collections: DocumentCollection[]): Promise<DocumentCollectionMetadata[]> {
-    // Example: assuming collection IDs are user IDs
-    const userIds = collections.map(collection => collection.id);
-    const users = await this.#userRepository.loadMany(userIds);
-
-    return collections.map(collection => {
-      const user = users.find(u => u.id == collection.id);
-      return {
-        name: user?.name ?? 'Unknown User',
-        group: 'Users'
-      };
-    });
-  }
-}
-```
-
-#### Initializing Categories and Types
-
-You can programmatically define and seed your document taxonomy.
-
-```typescript
-import { DocumentManagementService } from '@tstdl/base/document-management/server';
-import { DocumentPropertyDataType } from '@tstdl/base/document-management';
-import { defineEnum } from '@tstdl/base/enumeration';
-import { inject } from '@tstdl/base/injector';
-
-// Define enums for type-safe references
-export const PetCategory = defineEnum('PetCategory', { Pets: 'pets' });
-export const PetType = defineEnum('PetType', { Dog: 'dog', Cat: 'cat' });
-export const PetProperty = defineEnum('PetProperty', { Name: 'name', Age: 'age' });
-
-// In your application's startup logic
-async function seedDocumentTypes() {
-  const documentManagementService = inject(DocumentManagementService);
-
-  await documentManagementService.initializeCategoriesAndTypes(null, {
-    categoryLabels: { [PetCategory.Pets]: 'Pet Documents' },
-    categoryParents: { [PetCategory.Pets]: null },
-    typeLabels: {
-      [PetType.Dog]: 'Dog Papers',
-      [PetType.Cat]: 'Cat Papers'
-    },
-    typeCategories: {
-      [PetType.Dog]: PetCategory.Pets,
-      [PetType.Cat]: PetCategory.Pets
-    },
-    propertyConfigurations: {
-      [PetProperty.Name]: [DocumentPropertyDataType.Text, 'Pet Name'],
-      [PetProperty.Age]: [DocumentPropertyDataType.Integer, 'Pet Age']
-    },
-    typeProperties: {
-      [PetType.Dog]: [PetProperty.Name, PetProperty.Age],
-      [PetType.Cat]: [PetProperty.Name]
-    }
-  });
-}
-```
-
-## API Summary
-
-### Client-Side API
-
-| Class | Description |
-| :--- | :--- |
-| `DocumentManagementApi` | Provides a typed client for interacting with the document management backend API. |
-
-### Server-Side Configuration
-
-| Function | Description |
-| :--- | :--- |
-| `configureDocumentManagement(config)` | Registers and configures the document management module. |
-| `migrateDocumentManagementSchema()` | Applies database migrations for the module's tables. |
-
-### Server-Side Services
-
-| Class | Description |
-| :--- | :--- |
-| `DocumentManagementAuthorizationService` | Abstract service to be implemented by the application to control access to documents and collections. |
-| `DocumentManagementAncillaryService` | Abstract service to be implemented by the application to provide context-specific metadata for collections. |
-| `DocumentManagementService` | Core server-side service for managing documents, including initializing categories and types. |
-| `DocumentService` | Handles document creation, updates, and file operations. |
-| `DocumentFileService` | Manages physical file storage and retrieval from an object store. |
-| `DocumentWorkflowService` | Manages the lifecycle and progression of document workflows. |
-| `DocumentRequestService` | Manages document requests and templates. |