Frontend Architecture
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The KnowledgeVault frontend is a modern, single-page application built with React 18, TypeScript, and Vite. It provides a highly interactive interface for managing RAG (Retrieval-Augmented Generation) workflows, including document ingestion, semantic search, and a premium AI chat experience. The architecture emphasizes real-time feedback through Server-Sent Events (SSE), a robust multi-vault organizational structure, and a three-zone workspace layout designed for efficient knowledge management.
Sources: README.md:12, README.md:231, redesign/INTEGRATION_GUIDE.md:17
Core Component Structure
The UI is organized into a navigation rail with six primary sections: Chat, Search, Documents, Memory, Vaults, and Settings. The application uses a "three-zone" chat workspace to maximize utility during AI interactions.
Workspace Layout
The chat interface is divided into three functional zones:
- Session Rail (Left): Manages chat session history with grouping by time (Today, Yesterday, etc.) and search/pinning capabilities.
- Transcript Pane (Center): Displays the conversation flow, including message bubbles, streaming responses, and inline citation chips.
- Right Pane (Right): A resizable evidence panel that shows source documents, wiki references, and extracted information.
Sources: README.md:582-613, redesign/INTEGRATION_GUIDE.md:10-25
The diagram above illustrates the high-level layout of the application shell and the specialized three-zone workspace used for chat. Sources: README.md:582-613, redesign/INTEGRATION_GUIDE.md:46-75
State Management
The frontend utilizes Zustand for state management, featuring a normalized store to optimize rendering performance, particularly during high-frequency streaming events.
Store Normalization
To prevent unnecessary re-renders of the entire message list during streaming, the chat store is normalized using an ID-based map.
messageIds: An array of strings representing the order of messages.messagesById: A record mapping IDs to fullMessageobjects.appendToMessage: A granular action that mutates only the specific message receiving a stream chunk.
Sources: specs/chat-ui-ux-premiumization/SPEC.md:44-53, specs/chat-ui-ux-premiumization/SPEC.md:92-105
Key Store Features
| Feature | Implementation | Description |
|---|---|---|
| Persistence | Zustand Persist | Saves canvas width, themes, and session preferences to localStorage. |
| Auth State | useAuthStore | Manages JWT tokens, user profile, and session refresh logic. |
| Vault State | useVaultStore | Tracks the currently active vault and available vault list. |
| Chat State | useChatStore | Normalized message storage and streaming status. |
Sources: redesign/INTEGRATION_GUIDE.md:29-33, frontend/src/lib/api.ts:130-145, specs/chat-ui-ux-premiumization/SPEC.md:44-53
API and Data Flow
Data communication is handled via an Axios-based API client (apiClient) and a specialized streaming function for chat interactions.
Security and CSRF
The API layer implements a robust CSRF protection mechanism where logic is consolidated into lib/api.ts.
- Token Retrieval:
ensureCsrfToken()fetches tokens via/api/csrf-tokenwith promise deduplication. - Interceptors: An interceptor automatically attaches the
X-CSRF-Tokenheader to all mutating (POST, PUT, PATCH, DELETE) requests. - Automatic Recovery: On a CSRF-specific 403 error, the interceptor clears the cached token and retries the request once.
Sources: specs/pr5-pr6-frontend-cleanup/SPEC.md:17-30, frontend/src/lib/api.ts:37-88
Chat Streaming (SSE)
The chat system uses Server-Sent Events to provide real-time responses. The flow involves multiple event types that populate different parts of the UI.
This sequence shows how parseSSEStream in lib/api.ts dispatches various data types to UI callbacks during a single chat request. Sources: frontend/src/lib/api.ts:590-710, specs/wire-wiki-chat/SPEC.md:126-140
Citation Namespaces
The architecture supports three independent label spaces for evidence:
- [S#]: Document sources (Retrieved via RAG).
- [M#]: Memory records (User context).
- [W#]: Wiki claims (Compiled knowledge).
Sources: specs/wire-wiki-chat/SPEC.md:144-150, frontend/src/lib/api.ts:740-775
Component Specifications
Wiki Module
The Wiki system is integrated through specialized components that handle compiled knowledge.
WikiCards: Renders indigo-themed cards showing claims, confidence percentages, and provenance.WikiLintPanel: Displays findings from asynchronous linting jobs (e.g., contradictions or stale data).WikiPageDetail: Handles rich content rendering, including version history, attachments, and backlinks.
Sources: frontend/src/pages/WikiPage.tsx:143-220, frontend/src/pages/WikiPageDetail.tsx:1-50, specs/wire-wiki-chat/SPEC.md:58-65
Premium UI Features
| Component | File Path | Key Logic |
|---|---|---|
Composer | components/chat/Composer.tsx | Auto-growing textarea, paste-to-upload support, and IME composition guards. |
MarkdownMessage | components/chat/MarkdownMessage.tsx | Shared rendering pipeline with GFM support and syntax highlighting. |
WaitingIndicator | components/chat/WaitingIndicator.tsx | 100ms debounced indicator to provide feedback during SSE startup. |
ResizableHandle | components/canvas/ResizableHandle.tsx | Drag handle for the two-pane layout with persistent width state. |
Sources: specs/chat-ui-ux-premiumization/SPEC.md:58-85, specs/pr5-pr6-frontend-cleanup/SPEC.md:56-61, redesign/INTEGRATION_GUIDE.md:10-15
Technical Patterns
- Authentication: JWT-based with access tokens in memory and httpOnly refresh cookies. Automatic silent refresh is handled by the
apiClientresponse interceptor on 401 errors. - Styling: Tailwind CSS with semantic design tokens (e.g.,
--successfor verified states). - Animations: Framer Motion for smooth transitions, particularly in the resizable canvas and collapsible sidebars.
- Testing: Vitest for unit/integration testing with specialized mocks for the API and browser globals like
fetch.
Sources: frontend/src/lib/api.ts:160-210, specs/pr5-pr6-frontend-cleanup/SPEC.md:43-48, frontend/src/pages/WikiPage.test.tsx:10-50
Conclusion
The KnowledgeVault frontend architecture is designed for a performance-critical AI application. By utilizing normalized state management for streaming data and a centralized API layer for security, it provides a stable foundation for the complex "three-zone" workspace. The modularity of components like the Wiki and KMS subsystems allows the interface to scale with new knowledge management features while maintaining a premium user experience.