Admin & Application Settings UI
Relevant source files
The following files were used as context for generating this wiki page:
The Admin & Application Settings UI serves as the central management hub for the KnowledgeVault platform, allowing administrators to configure system-wide parameters, manage user access, and oversee the RAG (Retrieval-Augmented Generation) pipeline. This interface is built using React and a task-based 6-tab redesign that categorizes configurations into logical modules such as Models, Retrieval, and Wiki & Curator settings.
Sources: frontend/src/pages/SettingsPage.tsx:1-15, README.md:468-475
System Configuration Architecture
The settings architecture follows a "Source of Truth" pattern where the UI reflects configurations derived from three precedence levels: Key-Value store (KV), Environment Variables (env), and system defaults. The backend provides an effective_sources map to the frontend, which is used to label settings and indicate their origin.
Sources: frontend/src/pages/SettingsPage.tsx:1-10, frontend/src/lib/api.ts:241-245
Data Flow and Persistence
The settings management lifecycle involves fetching current states, managing local "dirty" states in a Zustand store, and persisting changes via specialized API endpoints.
Application Settings Tabs
The settings interface is organized into six functional tabs, each targeting a specific area of the application's RAG and administrative capabilities.
1. Overview & Health
Displays the global status of the system, including backend connectivity, embedding service availability, and chat model health.
Sources: frontend/src/pages/SettingsPage.tsx:191-201, frontend/src/lib/api.ts:476-483
2. Models & Connection
The "Models" tab is the single source of truth for LLM configurations. It allows administrators to define endpoints and model names for embeddings and chat, while providing visual indicators for which settings are locked by environment variables.
Sources: frontend/src/pages/SettingsPage.tsx:203-214, frontend/src/lib/api.ts:153-157
3. Retrieval & RAG
Configures the parameters for semantic search and context injection, including:
- Retrieval Top K: Number of chunks retrieved for context.
- Distance Threshold: Cosine similarity limit for relevance.
- Reranking: Integration with external reranker services.
| Parameter | Type | Default/Range | Description |
|---|---|---|---|
retrieval_top_k | integer | 12 | Number of document chunks to retrieve |
max_distance_threshold | float | 0.5 | Maximum distance for vector relevance |
reranking_enabled | boolean | false | Toggle for post-retrieval reranking |
Sources: frontend/src/lib/api.ts:213-228, README.md:144-152
4. Wiki & Curator
This section manages the Knowledge Compiler and the optional LLM Curator. The curator proposes wiki updates based on document ingest or chat queries.
Admin Management UI
The admin interface extends beyond application settings to include user and organization management, typically accessible via the AdminGuard.
User Management
Administrators can oversee user accounts through the AdminUsersPage, which supports:
- Updating user roles (Superadmin, Admin, Member, Viewer).
- Activating or deactivating user accounts.
- Managing organization and group memberships.
Sources: README.md:480-490, frontend/src/lib/api.ts:1145-1150
Connection & Security Interceptors
The UI interacts with the backend using a secure Axios client (apiClient) that implements timeout protections and CSRF (Cross-Site Request Forgery) interceptors.
| Feature | Implementation | Source |
|---|---|---|
| Timeout | 30,000ms (30 seconds) | frontend/src/lib/api.ts:154 |
| CSRF Logic | ensureCsrfToken interceptor | frontend/src/lib/api.ts:50-85 |
| JWT Auth | Authorization: Bearer <token> | frontend/src/lib/api.ts:162-167 |
Critical UI/UX Controls
Reindex Required Gate
Changes to "Reindex Required" fields (such as embedding models or chunk sizes) trigger a mandatory confirmation dialog. This prevents accidental invalidation of document embeddings without administrative acknowledgment.
Reindex Required Fields:
embedding_modelchunk_size_charsvector_metricchunk_overlap_chars
Sources: frontend/src/pages/SettingsPage.tsx:115-125, frontend/src/pages/SettingsPage.tsx:160-184
Save & Discard Logic
The interface utilizes a sticky footer that tracks "dirty" fields across tab switches.
- Dirty Indicators: Small dot icons appear on tab triggers if that specific tab contains unsaved changes.
- Discard: Reverts the local state to the last fetched snapshot.
- Save: Sends only the modified (dirty) payload to the
/api/settingsendpoint.
Sources: frontend/src/pages/SettingsPage.tsx:135-155, frontend/src/pages/SettingsPage.tsx:244-251
Conclusion
The Admin & Application Settings UI is a modular and safety-conscious interface designed for the complex requirements of a RAG system. By separating configuration into logical tasks and implementing strict validation gates for re-indexing, it ensures that system administrators can maintain performance and accuracy while managing multi-tenant user access.