Document Management UI
Relevant source files
The following files were used as context for generating this wiki page:
The Document Management UI is a critical component of the KnowledgeVault platform, providing users with the tools to upload, organize, and inspect documents used in the RAG (Retrieval-Augmented Generation) pipeline. It encompasses the entire lifecycle of a document within the frontend, from initial ingestion via drag-and-drop to detailed metadata inspection, tag management, and content previewing.
The system is designed to handle a wide variety of technical formats—including PDFs, Word documents, spreadsheets, and source code—and provides real-time status updates as files move through the asynchronous processing pipeline (parsing, chunking, and embedding). Sources: README.md:5-10, frontend/src/lib/api.ts:333-358
Document Lifecycle and Status Tracking
Documents transition through several phases after being uploaded. The UI tracks these states to provide feedback on the indexing progress.
Processing Phases
Asynchronous lifecycle details are reported via the phase field in the document status payload. These phases include:
- Queued: Waiting for processing resources.
- Parsing / Extracting Text: Converting raw bytes into a machine-readable format.
- Chunking: Breaking text into segments based on
CHUNK_SIZE_CHARS. - Embedding: Generating vector representations via the embedding service.
- Writing Index: Persisting data to the LanceDB vector store.
Sources: frontend/src/lib/api.ts:386-391, frontend/src/fixtures/documents.ts:140-165
Status Indicators
The UI maps internal states to four canonical status values for simplified user display:
| Status | Description |
|---|---|
pending | Document is awaiting initial processing. |
processing | Document is currently being parsed, chunked, or embedded. |
indexed | Document is fully processed and available for RAG retrieval. |
error | Processing failed; details are typically available in error_message. |
Sources: frontend/src/lib/api.ts:384-388, frontend/src/fixtures/documents.ts:114-122
Document Ingestion Architecture
Ingestion occurs primarily through the uploadDocument API, which supports progress tracking and vault-specific routing.
The system enforces a maximum file size of 50 MB for uploads. Sources: frontend/src/lib/api.ts:702-734, specs/pr5-pr6-frontend-cleanup/SPEC.md:46
Detailed Document Inspection
The DocumentDetailPage provides a comprehensive view of a specific document's metadata and content.
Metadata and Statistics
The UI displays key technical details derived from the Document and DocumentStatusResponse interfaces:
- File Details: Filename, MIME type, and formatted file size.
- Processing Stats: Total chunk count and
chunks_failed(indicating segments dropped by embedding failures). - Timestamps: Created at and processed at dates.
Sources: frontend/src/pages/DocumentDetailPage.tsx:142-167, frontend/src/lib/api.ts:333-358
Content Preview
The UI supports inline previews for specific file types:
- Text Previews: For
.txt,.md,.csv,.json,.yaml, etc. Previews are capped at 5 MB to prevent browser performance degradation. - PDF Previews: Rendered via an iframe using a blob URL generated from
getDocumentRawBlob.
Sources: frontend/src/pages/DocumentDetailPage.tsx:78-112, frontend/src/lib/api.ts:752-763
Organization and Tagging
Documents can be organized using tags and folders, which are vault-scoped.
Tag Management
The UI allows users to fetch all available tags for a vault and assign them to documents. The setDocumentTags function replaces the current tag set for a document with a new list of IDs.
Sources: frontend/src/lib/api.ts:553-561, frontend/src/pages/DocumentDetailPage.tsx:170-198
Deletion and Undo Logic
To prevent accidental data loss, the UI implements an "Undo" pattern for document deletion.
- User triggers delete.
- The document is hidden optimistically from the UI.
- A toast notification appears with an "Undo" action.
- A 3-second delay occurs before the
deleteDocumentAPI is called. - If "Undo" is clicked, the timer is cleared and the document is restored.
Sources: specs/pr5-pr6-frontend-cleanup/SPEC.md:47-49, specs/pr5-pr6-frontend-cleanup/SPEC.md:81-87
Summary of Key Components
| Component | Responsibility |
|---|---|
DocumentDetailPage | Renders metadata, tag management, and file previews. |
StatusBadge | Provides visual indication of document processing state. |
apiClient | Handles communication with /api/documents endpoints including progress events. |
FileIcon | Maps file extensions to specific visual icons. |
Sources: frontend/src/pages/DocumentDetailPage.tsx, frontend/src/lib/api.ts
The Document Management UI ensures that technical users can maintain a high-quality knowledge base by providing transparency into the automated ingestion pipeline and offering robust tools for manual curation and inspection.