docs/design.md

Design Philosophy

Core Beliefs

1. Privacy-First: All data stays local, no tracking, no cloud dependencies
2. Minimalist UI: Clean, uncluttered interface focused on core functionality
3. Browser-Based AI: Models run locally in the browser when possible
4. Efficient Resource Usage: On-demand model loading and caching
5. Open Source: Transparent development, community contributions welcome

Design Principles

User Interface

• Minimal visual clutter with Mantine v9 components
• Clear hierarchy and information architecture
• Keyboard-first navigation with comprehensive shortcuts
• Semantic HTML and ARIA labels for WCAG 2.1 AA compliance
• Responsive design for desktop and mobile
• Dark mode by default (via Mantine's MantineProvider)

Performance

• Lazy loading for routes and components with React.lazy()
• Optimized bundle size using Vite 8 build optimizations
• Efficient state management with create-pubsub
• Caching strategies for search results and AI responses
• WebGPU detection for automatic GPU-accelerated inference
• Bundle analysis with rollup-plugin-visualizer

Accessibility

• WCAG-aligned where implemented
• Screen reader support
• Keyboard navigation
• ARIA labels on select interactive elements (e.g. chat input, history actions)
• Focus indicators

Component Design

• Feature-based component organization in client/components/
• Tests co-located for select components (e.g. SearchForm, MainPage, SearchResultsSection); broader test coverage is still being built out
• Consistent use of Mantine UI v9 components and hooks
• Custom hooks for reusable logic in client/hooks/
• Business logic separated into client/modules/
• Proper TypeScript typing throughout with strict mode
• React 19 patterns with function components (no React.FC)

Technology Integration

AI & Search

• Multiple inference engines: Wllama (WebGPU or CPU), OpenAI-compatible APIs
• Privacy-first local processing when possible
• SearXNG integration for web search
• Graceful fallbacks for unsupported browsers

Development Experience

• Hot Module Replacement with Vite
• Biome for consistent formatting and linting
• Comprehensive testing with Vitest and Testing Library
• Docker-based development environment

Related Topics

• UI Components: docs/ui-components.md - Component implementation details
• Project Structure: docs/project-structure.md - Directory organization
• Coding Conventions: docs/coding-conventions.md - Code style guidelines