You are an expert AI Assistant tasked with building a Single Page Application (SPA) for an innovative AI-powered documentation exploration tool. This tool aims to revolutionize how users interact with technical documentation by leveraging a virtual filesystem metaphor, overcoming the limitations of traditional Retrieval-Augmented Generation (RAG) systems. Users should be able to navigate, search, and query documentation as if they were exploring a code repository.
## 1. PROJECT OVERVIEW
**Project Title:** DocuVerse Explorer
**Objective:** To create a web application that provides users with an intuitive and efficient way to access and understand complex technical documentation. Unlike traditional RAG systems that struggle with context spread across multiple documents or specific phrasing, DocuVerse Explorer treats documentation pages and sections as files and directories within a virtual filesystem. This allows for precise searching, full-text reading, and context-aware querying, mimicking the experience of navigating a codebase.
**Value Proposition:** Faster, more accurate, and contextually richer information retrieval from large documentation sets. Enables users to 'explore' docs, find exact syntax, and understand information spanning multiple sections or pages with ease, reducing research time and improving comprehension. Solves the latency and infrastructure cost issues associated with sandboxed environments for RAG.
## 2. TECH STACK
* **Frontend Framework:** React (using Vite for fast development setup)
* **UI Library/Framework:** Tailwind CSS for utility-first styling.
* **State Management:** Zustand for efficient and simple global state management.
* **Routing:** React Router DOM for client-side routing (though for a single page, this might be minimal).
* **Icons:** React Icons for a comprehensive icon library.
* **Utilities:** Lodash for utility functions, Axios for potential API calls (if backend is introduced later).
* **Build Tool:** Vite
## 3. CORE FEATURES & USER FLOWS
**A. Virtual Filesystem Navigation:**
* **User Flow:** Upon application load, the user sees a representation of the documentation structured as a hierarchical filesystem. They can see folders (representing sections or categories) and files (representing individual documentation pages). Users can click on folders to expand/collapse them and view their contents. Clicking on a file opens it.
* **Details:** The interface should visually mimic a file explorer (e.g., tree view). Expand/collapse icons, file/folder icons, and breadcrumbs for current location are essential.
**B. Advanced Search (grep-like):**
* **User Flow:** A prominent search bar allows users to type queries. The system searches file names, section titles, and full document content. Results are displayed as a list of files/sections, potentially with a snippet showing the match. Users can click a search result to navigate directly to that file/section.
* **Details:** Supports basic string matching. Future iterations could include regex support. Search should be fast and responsive. Displaying the path within the virtual filesystem for each result is crucial.
**C. Document/Section Viewer:**
* **User Flow:** When a user clicks on a file (document page) or a specific section (which acts like a file within a directory), its content is displayed in a dedicated viewer pane. The viewer should clearly indicate the title, breadcrumbs, and the content itself, including any markdown formatting.
* **Details:** Supports Markdown rendering. Should highlight the currently viewed file in the navigation pane. Easy navigation back to the filesystem view or up the directory tree is required.
**D. AI-Powered Q&A (Contextual):**
* **User Flow:** Within the document viewer or a dedicated AI chat panel, users can ask questions related to the currently viewed document or the entire documentation set. The AI provides answers based on the indexed documentation, referencing specific sections or files. For instance, asking 'How do I configure X?' while viewing a configuration guide should yield a relevant answer possibly pointing to specific lines or sections.
* **Details:** The AI should leverage the virtual filesystem structure for context. Answers should ideally include citations or links back to the source files/sections. This feature might initially rely on pre-computed embeddings or a simplified indexing strategy for MVP.
## 4. UI/UX DESIGN
* **Layout:** A two- or three-pane layout is recommended:
1. **Left Pane:** Collapsible navigation tree (Virtual Filesystem).
2. **Center/Main Pane:** Content viewer for the selected document/section, or search results.
3. **(Optional) Right Pane:** AI Chat/Q&A interface.
* A persistent header for the global search bar and application title.
* **Color Palette:** Clean, professional, and developer-focused. Primary: Dark/Muted Blue or Charcoal (#1a202c or similar). Secondary: Lighter Grays for backgrounds/borders (#2d3748, #4a5568). Accent: A brighter, energetic color like Cyan or Teal (#00bcd4 or #4dc0b5) for interactive elements, links, and highlights. Use subtle variations for different states (hover, active).
* **Typography:** Monospace font for code snippets and technical terms (e.g., 'Fira Code', 'Source Code Pro'). Sans-serif font for UI elements and general text (e.g., 'Inter', 'Roboto', 'Open Sans'). Clear hierarchy using font sizes and weights.
* **Responsive Design:** The layout should adapt gracefully. On smaller screens, the navigation pane might be hidden behind a hamburger menu. The content pane should take precedence. Ensure touch targets are adequately sized.
* **Visual Metaphor:** Use folder and file icons consistently. Breadcrumbs should be clear. Loading states should be indicated with spinners or skeleton screens.
## 5. COMPONENT BREAKDOWN
* **`App.jsx`:** Main application wrapper. Handles routing setup (if any), global layout, and state provider setup.
* **`Layout.jsx`:** Defines the main application structure (header, sidebars, content area).
* **`Header.jsx`:** Contains the application title and the global search bar.
* **`FileSystemNavigator.jsx`:**
* Props: `docsStructure` (tree data), `onFileSelect` (callback).
* Renders the tree view of folders and files. Handles expand/collapse logic. Uses `TreeNode.jsx`.
* **`TreeNode.jsx`:**
* Props: `node` (file/folder object), `level` (nesting depth), `selectedPath` (current path).
* Recursively renders a single node (folder or file) in the tree. Handles click events.
* **`DocumentViewer.jsx`:**
* Props: `content` (markdown string), `filePath` (string), `onQuestionSubmit` (callback).
* Renders the document content using a Markdown parser. Displays file path/breadcrumbs. Includes a text area for AI questions.
* **`SearchBar.jsx`:**
* Props: `onSearch` (callback).
* Input element for global search. Triggers search on input change or enter press.
* **`SearchResults.jsx`:**
* Props: `results` (array of file matches), `onResultSelect` (callback).
* Displays the list of search results. Each result shows file name, path, and snippet.
* **`AIChatPanel.jsx`:**
* Props: `conversationHistory` (array), `onSubmitQuery` (callback), `isLoading` (boolean).
* Manages the display of AI conversation. Includes input for user queries and shows responses.
* **`LoadingSpinner.jsx`:** Simple component to display a loading indicator.
## 6. DATA MODEL & STATE MANAGEMENT
* **State:** Managed primarily by Zustand.
* `docsStructure`: `{ id: string, name: string, type: 'folder' | 'file', path: string, children?: DocsNode[], content?: string }[]` - Represents the virtual filesystem tree.
* `currentPath`: `string` - The current location in the virtual filesystem.
* `selectedFile`: `string | null` - The path of the currently open file.
* `documentContent`: `string` - The content of the selected document.
* `searchResults`: `Array<{ path: string, name: string, snippet: string }>` - Results from the search.
* `aiConversation`: `Array<{ sender: 'user' | 'ai', message: string }>` - History of AI interactions.
* `isLoading`: `boolean` - Global loading state.
* `error`: `string | null` - Any error message.
* **Mock Data:** The `docsStructure` will be populated with mock data representing a sample documentation set. The AI responses will also be mocked initially.
**Example `docsStructure` Node:**
```json
{
"id": "getting-started",
"name": "Getting Started",
"type": "folder",
"path": "/docs/getting-started",
"children": [
{
"id": "installation",
"name": "Installation Guide",
"type": "file",
"path": "/docs/getting-started/installation.md",
"content": "# Installation\n\nFollow these steps to install..."
},
{
"id": "quick-start",
"name": "Quick Start Guide",
"type": "file",
"path": "/docs/getting-started/quick-start.md",
"content": "# Quick Start\n\nGet up and running in 5 minutes..."
}
]
}
```
**Example `aiConversation` Entry:**
```json
{
"sender": "user",
"message": "How do I install the latest version?"
}
```
## 7. ANIMATIONS & INTERACTIONS
* **File System Navigation:** Smooth expand/collapse animations for folders. Subtle hover effects on file/folder names indicating interactivity.
* **Search Results:** Fade-in effect for search results list. Hover effect on results for visual feedback.
* **Loading States:** Use skeleton loaders or subtle spinners within panes while content is loading (documents, search results, AI responses). Avoid jarring full-page reloads.
* **Transitions:** Smooth transitions between different views (e.g., file viewer to search results).
* **Micro-interactions:** Visual feedback on button clicks, input focus states.
## 8. EDGE CASES & ACCESSIBILITY
* **Empty States:** Display user-friendly messages when:
* No documentation is loaded.
* Search yields no results.
* AI conversation is empty.
* **Error Handling:** Gracefully handle errors during data fetching or AI processing. Display informative error messages to the user. Implement basic retry mechanisms where appropriate.
* **Validation:** Basic input validation for search queries (e.g., prevent excessively long queries).
* **Accessibility (a11y):**
* Use semantic HTML5 elements.
* Ensure sufficient color contrast.
* Implement keyboard navigation for all interactive elements (file tree, search, buttons).
* Use ARIA attributes where necessary (e.g., for dynamic content updates, expanded/collapsed states).
* Ensure focus management is logical.
## 9. SAMPLE DATA (Mock Data for `docsStructure`)
```json
[
{
"id": "introduction",
"name": "Introduction",
"type": "folder",
"path": "/docs/introduction",
"children": [
{
"id": "welcome",
"name": "Welcome to DocuVerse",
"type": "file",
"path": "/docs/introduction/welcome.md",
"content": "# Welcome to DocuVerse!\n\nThis is your central hub for all documentation. Explore the filesystem-like interface to find exactly what you need."
},
{
"id": "features",
"name": "Core Features Overview",
"type": "file",
"path": "/docs/introduction/features.md",
"content": "# Core Features\n\n- Virtual Filesystem Navigation\n- Advanced Search Capabilities\n- AI-Powered Q&A"
}
]
},
{
"id": "usage",
"name": "Usage Guide",
"type": "folder",
"path": "/docs/usage",
"children": [
{
"id": "navigation",
"name": "Navigating the Docs",
"type": "file",
"path": "/docs/usage/navigation.md",
"content": "# Navigating the Docs\n\nThe primary interface is a tree view similar to your file explorer. Click folders to expand and files to view content. Use the breadcrumbs at the top to understand your location."
},
{
"id": "searching",
"name": "Advanced Search",
"type": "file",
"path": "/docs/usage/searching.md",
"content": "# Advanced Search\n\nUse the search bar in the header to find information across all documents. Type keywords, exact phrases, or even partial filenames. Results will show snippets."
}
]
},
{
"id": "ai_integration",
"name": "AI Integration",
"type": "folder",
"path": "/docs/ai_integration",
"children": [
{
"id": "qa_basics",
"name": "Basic Q&A",
"type": "file",
"path": "/docs/ai_integration/qa_basics.md",
"content": "# Basic Q&A\n\nAsk questions directly in the chat panel. The AI uses the context of the currently viewed document or the entire knowledge base to provide answers."
},
{
"id": "context_awareness",
"name": "Context Awareness",
"type": "file",
"path": "/docs/ai_integration/context_awareness.md",
"content": "# Context Awareness\n\nThe AI understands the structure of the documentation. If you ask about configuring a specific module while viewing its configuration file, the AI will prioritize that context."
}
]
},
{
"id": "config_example",
"name": "config.yaml",
"type": "file",
"path": "/docs/config_example.yaml",
"content": "# Sample Configuration File\n\n```yaml\nserver:\n port: 8080\n host: localhost\ndatabase:\n type: postgresql\n url: \"postgres://user:pass@host:port/db\"\n"
}
]
```
## 10. DEPLOYMENT NOTES
* **Build:** Use Vite's build command (`vite build`). Ensure the `base` path is configured correctly if deploying to a sub-directory.
* **Environment Variables:** Use `.env` files for configuration. Potential variables: `VITE_API_ENDPOINT` (for future backend integration), `VITE_AI_MODEL_NAME`.
* **Performance:** Optimize image loading if any are present. Code splitting can be handled by Vite. Ensure efficient state updates to prevent unnecessary re-renders. Lazy load components where appropriate.
* **Hosting:** Can be deployed as a static site on platforms like Vercel, Netlify, GitHub Pages, or S3/CloudFront.
* **Search Indexing:** For MVP, search can be done client-side on the loaded `docsStructure` JSON. For larger datasets, consider a dedicated client-side search index library (like Lunr.js) or a backend search service.