331 lines
7.8 KiB
Markdown
331 lines
7.8 KiB
Markdown
# Archon UI - Knowledge Engine Web Interface
|
|
|
|
A modern React-based web interface for the Archon Knowledge Engine MCP Server. Built with TypeScript, Vite, and Tailwind CSS.
|
|
|
|
## 🎨 UI Overview
|
|
|
|
Archon UI provides a comprehensive dashboard for managing your AI's knowledge base:
|
|
|
|
|
|
|
|
### Key Features
|
|
|
|
- **📊 MCP Dashboard**: Monitor and control the MCP server
|
|
- **⚙️ Settings Management**: Configure credentials and RAG strategies
|
|
- **🕷️ Web Crawling**: Crawl documentation sites and build knowledge base
|
|
- **📚 Knowledge Management**: Browse, search, and organize knowledge items
|
|
- **💬 Interactive Chat**: Test RAG queries with real-time responses
|
|
- **📈 Real-time Updates**: WebSocket-based live updates across the UI
|
|
|
|
## 🏗️ Architecture
|
|
|
|
### Technology Stack
|
|
|
|
- **React 18.3**: Modern React with hooks and functional components
|
|
- **TypeScript**: Full type safety and IntelliSense support
|
|
- **Vite**: Fast build tool and dev server
|
|
- **Tailwind CSS**: Utility-first styling
|
|
- **Framer Motion**: Smooth animations and transitions
|
|
- **Lucide Icons**: Beautiful and consistent iconography
|
|
- **React Router**: Client-side routing
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
archon-ui-main/
|
|
├── src/
|
|
│ ├── components/ # Reusable UI components
|
|
│ │ ├── ui/ # Base UI components (Button, Card, etc.)
|
|
│ │ ├── layouts/ # Layout components (Sidebar, Header)
|
|
│ │ └── animations/ # Animation components
|
|
│ ├── pages/ # Page components
|
|
│ │ ├── MCPPage.tsx # MCP Dashboard
|
|
│ │ ├── Settings.tsx # Settings page
|
|
│ │ ├── Crawl.tsx # Web crawling interface
|
|
│ │ ├── KnowledgeBase.tsx # Knowledge management
|
|
│ │ └── Chat.tsx # RAG chat interface
|
|
│ ├── services/ # API and service layers
|
|
│ │ ├── api.ts # Base API configuration
|
|
│ │ ├── mcpService.ts # MCP server communication
|
|
│ │ └── chatService.ts # Chat/RAG service
|
|
│ ├── contexts/ # React contexts
|
|
│ │ └── ToastContext.tsx # Toast notifications
|
|
│ ├── hooks/ # Custom React hooks
|
|
│ │ └── useStaggeredEntrance.ts # Animation hook
|
|
│ ├── types/ # TypeScript type definitions
|
|
│ └── lib/ # Utility functions
|
|
├── public/ # Static assets
|
|
└── test/ # Test files
|
|
```
|
|
|
|
## 📄 Pages Documentation
|
|
|
|
### 1. MCP Dashboard (`/mcp`)
|
|
|
|
The central control panel for the MCP server.
|
|
|
|
**Components:**
|
|
- **Server Control Panel**: Start/stop server, view status, select transport mode
|
|
- **Server Logs Viewer**: Real-time log streaming with auto-scroll
|
|
- **Available Tools Table**: Dynamic tool discovery and documentation
|
|
- **MCP Test Panel**: Interactive tool testing interface
|
|
|
|
**Features:**
|
|
- Dual transport support (SSE/stdio)
|
|
- Real-time status polling (5-second intervals)
|
|
- WebSocket-based log streaming
|
|
- Copy-to-clipboard configuration
|
|
- Tool parameter validation
|
|
|
|
### 2. Settings (`/settings`)
|
|
|
|
Comprehensive configuration management.
|
|
|
|
**Sections:**
|
|
- **Credentials**:
|
|
- OpenAI API key (encrypted storage)
|
|
- Supabase connection details
|
|
- MCP server configuration
|
|
- **RAG Strategies**:
|
|
- Contextual Embeddings toggle
|
|
- Hybrid Search toggle
|
|
- Agentic RAG (code extraction) toggle
|
|
- Reranking toggle
|
|
|
|
**Features:**
|
|
- Secure credential storage with encryption
|
|
- Real-time validation
|
|
- Toast notifications for actions
|
|
- Default value management
|
|
|
|
### 3. Web Crawling (`/crawl`)
|
|
|
|
Interface for crawling documentation sites.
|
|
|
|
**Components:**
|
|
- **URL Input**: Smart URL validation
|
|
- **Crawl Options**: Max depth, concurrent sessions
|
|
- **Progress Monitoring**: Real-time crawl status
|
|
- **Results Summary**: Pages crawled, chunks stored
|
|
|
|
**Features:**
|
|
- Intelligent URL type detection
|
|
- Sitemap support
|
|
- Recursive crawling
|
|
- Batch processing
|
|
|
|
### 4. Knowledge Base (`/knowledge`)
|
|
|
|
Browse and manage your knowledge items.
|
|
|
|
**Components:**
|
|
- **Knowledge Grid**: Card-based knowledge display
|
|
- **Search/Filter**: Search by title, type, tags
|
|
- **Knowledge Details**: View full item details
|
|
- **Actions**: Delete, refresh, organize
|
|
|
|
**Features:**
|
|
- Pagination support
|
|
- Real-time updates via WebSocket
|
|
- Type-based filtering (technical/business)
|
|
- Metadata display
|
|
|
|
### 5. RAG Chat (`/chat`)
|
|
|
|
Interactive chat interface for testing RAG queries.
|
|
|
|
**Components:**
|
|
- **Chat Messages**: Threaded conversation view
|
|
- **Input Area**: Query input with source selection
|
|
- **Results Display**: Formatted RAG results
|
|
- **Source Selector**: Filter by knowledge source
|
|
|
|
**Features:**
|
|
- Real-time streaming responses
|
|
- Source attribution
|
|
- Markdown rendering
|
|
- Copy functionality
|
|
|
|
## 🧩 Component Library
|
|
|
|
### Base UI Components
|
|
|
|
#### Button
|
|
```tsx
|
|
<Button
|
|
variant="primary|secondary|ghost"
|
|
size="sm|md|lg"
|
|
accentColor="blue|green|purple|orange|pink"
|
|
onClick={handleClick}
|
|
>
|
|
Click me
|
|
</Button>
|
|
```
|
|
|
|
#### Card
|
|
```tsx
|
|
<Card accentColor="blue" className="p-6">
|
|
<h3>Card Title</h3>
|
|
<p>Card content</p>
|
|
</Card>
|
|
```
|
|
|
|
#### LoadingSpinner
|
|
```tsx
|
|
<LoadingSpinner size="sm|md|lg" />
|
|
```
|
|
|
|
### Layout Components
|
|
|
|
#### Sidebar
|
|
- Collapsible navigation
|
|
- Active route highlighting
|
|
- Icon + text navigation items
|
|
- Responsive design
|
|
|
|
#### Header
|
|
- Dark mode toggle
|
|
- User menu
|
|
- Breadcrumb navigation
|
|
|
|
### Animation Components
|
|
|
|
#### PageTransition
|
|
Wraps pages with smooth fade/slide animations:
|
|
```tsx
|
|
<PageTransition>
|
|
<YourPageContent />
|
|
</PageTransition>
|
|
```
|
|
|
|
## 🔌 Services
|
|
|
|
### mcpService
|
|
Handles all MCP server communication:
|
|
- `startServer()`: Start the MCP server
|
|
- `stopServer()`: Stop the MCP server
|
|
- `getStatus()`: Get current server status
|
|
- `streamLogs()`: WebSocket log streaming
|
|
- `getAvailableTools()`: Fetch MCP tools
|
|
|
|
### api
|
|
Base API configuration with:
|
|
- Automatic error handling
|
|
- Request/response interceptors
|
|
- Base URL configuration
|
|
- TypeScript generics
|
|
|
|
### chatService
|
|
RAG query interface:
|
|
- `sendMessage()`: Send RAG query
|
|
- `streamResponse()`: Stream responses
|
|
- `getSources()`: Get available sources
|
|
|
|
## 🎨 Styling
|
|
|
|
### Tailwind Configuration
|
|
- Custom color palette
|
|
- Dark mode support
|
|
- Custom animations
|
|
- Responsive breakpoints
|
|
|
|
### Theme Variables
|
|
```css
|
|
--primary: Blue accent colors
|
|
--secondary: Gray/neutral colors
|
|
--success: Green indicators
|
|
--warning: Orange indicators
|
|
--error: Red indicators
|
|
```
|
|
|
|
## 🚀 Development
|
|
|
|
### Setup
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Start dev server
|
|
npm run dev
|
|
|
|
# Build for production
|
|
npm run build
|
|
|
|
# Run tests
|
|
npm test
|
|
```
|
|
|
|
### Environment Variables
|
|
```env
|
|
VITE_API_URL=http://localhost:8080
|
|
```
|
|
|
|
### Hot Module Replacement
|
|
Vite provides instant HMR for:
|
|
- React components
|
|
- CSS modules
|
|
- TypeScript files
|
|
|
|
## 🧪 Testing
|
|
|
|
### Unit Tests
|
|
- Component testing with React Testing Library
|
|
- Service mocking with MSW
|
|
- Hook testing with @testing-library/react-hooks
|
|
|
|
### Integration Tests
|
|
- Page-level testing
|
|
- API integration tests
|
|
- WebSocket testing
|
|
|
|
## 📦 Build & Deployment
|
|
|
|
### Docker Support
|
|
```dockerfile
|
|
FROM node:18-alpine
|
|
WORKDIR /app
|
|
COPY package*.json ./
|
|
RUN npm ci
|
|
COPY . .
|
|
RUN npm run build
|
|
EXPOSE 5173
|
|
CMD ["npm", "run", "preview"]
|
|
```
|
|
|
|
### Production Optimization
|
|
- Code splitting by route
|
|
- Lazy loading for pages
|
|
- Image optimization
|
|
- Bundle size analysis
|
|
|
|
## 🔧 Configuration Files
|
|
|
|
### vite.config.ts
|
|
- Path aliases
|
|
- Build optimization
|
|
- Development server config
|
|
|
|
### tsconfig.json
|
|
- Strict type checking
|
|
- Path mappings
|
|
- Compiler options
|
|
|
|
### tailwind.config.js
|
|
- Custom theme
|
|
- Plugin configuration
|
|
- Purge settings
|
|
|
|
## 🤝 Contributing
|
|
|
|
### Code Style
|
|
- ESLint configuration
|
|
- Prettier formatting
|
|
- TypeScript strict mode
|
|
- Component naming conventions
|
|
|
|
### Git Workflow
|
|
- Feature branches
|
|
- Conventional commits
|
|
- PR templates
|
|
- Code review process
|