Hugging Face's logo

Spaces:
Felladrin
/
MiniSearch
Running

App Files Community
1
MiniSearch / agents.md
github-actions[bot]
Sync from https://github.com/felladrin/MiniSearch
0721faa
preview code
|
Raw
History Blame Contribute Delete
10.1 kB

MiniSearch Agent Guidelines

This is your navigation hub. Start here, follow the links, and return when you need orientation.

Before You Start

New to this codebase? Read in this order:

  1. docs/quick-start.md - Get it running
  2. docs/overview.md - Understand the system
  3. docs/project-structure.md - Navigate the code

Making changes? Check:

  • docs/coding-conventions.md - Code style
  • docs/development-commands.md - Available commands
  • docs/pull-requests.md - How to submit

Repository Map

Getting Started

  • docs/quick-start.md - Installation, first run, verification
  • docs/overview.md - System architecture and data flow
  • docs/project-structure.md - Directory layout and component organization

Configuration & Setup

  • docs/configuration.md - Environment variables and settings reference
  • docs/security.md - Access control, privacy, and security model

Core Functionality

  • docs/ai-integration.md - AI inference types (Wllama, OpenAI, AI Horde, Internal)
  • docs/ui-components.md - Component architecture and PubSub patterns
  • docs/search-history.md - History database schema and management
  • docs/conversation-memory.md - Token budgeting and rolling summaries
  • docs/reranking.md - Reranker subsystem and model lifecycle
  • docs/glossary.md - Codebase-specific terms and domain concepts

Development

  • docs/development-commands.md - Docker, npm, and testing commands
  • docs/coding-conventions.md - Style guide and patterns
  • docs/pull-requests.md - PR process and merge philosophy
  • docs/core-technologies.md - Technology stack and dependencies
  • docs/design.md - UI/UX design principles

Agent Decision Tree 

Need to:
├── Add a feature?
│   ├── UI component → docs/ui-components.md
│   ├── AI integration → docs/ai-integration.md
│   ├── Search functionality → client/modules/search.ts
│   └── Settings option → docs/configuration.md
├── Fix a bug?
│   ├── UI issue → Check component + PubSub channels
│   ├── AI not working → docs/ai-integration.md + browser console
│   ├── Search failing → Check SearXNG + server hooks
│   └── Build error → docs/development-commands.md
├── Configure deployment?
│   ├── Environment variables → docs/configuration.md
│   ├── Access control → docs/security.md
│   └── Docker setup → docs/overview.md
└── Understand data flow?
    ├── Search flow → client/modules/search.ts
    ├── AI generation → client/modules/textGeneration.ts
    ├── State management → docs/ui-components.md
    └── History/Chat → docs/search-history.md + docs/conversation-memory.md

Key Files Reference

Entry Points

  • client/index.tsx - React app initialization
  • vite.config.ts - Vite dev server with hooks
  • Dockerfile - Multi-stage container build

Business Logic Modules

  • client/modules/search.ts - Search orchestration and caching
  • client/modules/textGeneration.ts - AI response flow
  • client/modules/pubSub.ts - All PubSub channels
  • client/modules/settings.ts - Settings management
  • client/modules/history.ts - Search history database

Server-Side Modules

  • server/searchEndpointServerHook.ts - /search endpoints
  • server/internalApiEndpointServerHook.ts - /inference proxy
  • server/webSearchService.ts - SearXNG integration
  • server/rerankerService.ts - Local result reranking

UI Components

  • client/components/App/ - Application shell with error boundaries
  • client/components/Search/Form/ - Search input and form
  • client/components/Search/Results/ - Textual and graphical results display
  • client/components/Search/History/ - History drawer and button
  • client/components/AiResponse/ - AI response display and chat interface
  • client/components/Pages/Main/ - Main page layout
  • client/components/Pages/Main/Menu/ - Settings drawers (AI, Search, Interface, History, Voice, Actions)
  • client/components/Pages/AccessPage.tsx - Access key validation page
  • client/components/Analytics/SearchStats.tsx - Search analytics cards
  • client/components/Logs/ - Application logging modal
  • client/components/Settings/HistorySettings.tsx - History configuration UI

Client Modules

  • client/modules/pubSub.ts - All PubSub channels for state management
  • client/modules/search.ts - Search orchestration and IndexedDB caching
  • client/modules/textGeneration.ts - AI response generation and chat handling
  • client/modules/textGenerationWithWllama.ts - Browser-based inference
  • client/modules/textGenerationWithOpenAi.ts - OpenAI-compatible API inference
  • client/modules/textGenerationWithHorde.ts - AI Horde distributed inference
  • client/modules/textGenerationWithInternalApi.ts - Internal API proxy inference
  • client/modules/settings.ts - Default settings and inference type definitions
  • client/modules/history.ts - IndexedDB persistence for searches and chat
  • client/modules/wllama.ts - Wllama model configuration and management
  • client/modules/webGpu.ts - WebGPU availability detection ("gpu" in navigator)
  • client/modules/querySuggestions.ts - Search suggestion UI, stored in IndexedDB
  • client/modules/relatedSearchQuery.ts - Generates related search queries
  • client/modules/followUpQuestions.ts - Generates follow-up questions via followUpQuestionPubSub
  • client/modules/accessKey.ts - Validates and stores access keys using argon2id hashing and localStorage
  • client/modules/parentWindow.ts - PostMessage API for embedding in parent windows
  • client/modules/searchTokenHash.ts - CSRF protection token generation
  • client/modules/systemPrompt.ts - System prompt templates
  • client/modules/logEntries.ts - Application logging with unique IDs
  • client/modules/appInfo.ts - Application metadata and version info
  • client/modules/keyboard.ts - Keyboard shortcut handling
  • client/modules/stringFormatters.ts - Text formatting utilities
  • client/modules/types.ts - Shared TypeScript type definitions

Server Modules

  • server/searchEndpointServerHook.ts - /search/text and /search/images endpoints
  • server/internalApiEndpointServerHook.ts - /inference proxy to self-hosted API
  • server/validateAccessKeyServerHook.ts - Access key validation endpoint
  • server/statusEndpointServerHook.ts - /status health check endpoint
  • server/rerankerServiceHook.ts - Reranker model lifecycle management
  • server/compressionServerHook.ts - gzip/brotli compression for responses
  • server/crossOriginServerHook.ts - COOP/COEP headers for SharedArrayBuffer
  • server/cacheServerHook.ts - Cache-Control headers (preview server only)
  • server/webSearchService.ts - SearXNG integration with circuit breaker and retry logic
  • server/rerankerService.ts - Reranker service (ONNX Runtime inference)
  • server/rankSearchResults.ts - Score-based filtering and result reordering
  • server/searchToken.ts - CSRF token generation and storage
  • server/verifiedTokens.ts - In-memory Set<string> of verified session tokens
  • server/verifyTokenAndRateLimit.ts - Token verification and rate limiting
  • server/handleTokenVerification.ts - Search token validation logic
  • server/searchesSinceLastRestart.ts - In-memory search counters for analytics
  • server/downloadFileFromHuggingFaceRepository.ts - Downloads model files from HuggingFace

Hooks

  • client/hooks/useSearchHistory.ts - Search history management from IndexedDB
  • client/hooks/useHistoryRestore.ts - Restores full search state from history
  • client/hooks/useDrawerState.ts - Drawer open/close state with logging

Common Tasks Quick Reference

Add a new AI model

  1. Add to client/modules/wllama.ts
  2. Update docs/ai-integration.md
  3. Update docs/configuration.md defaults

Add a new setting

  1. Add to client/modules/settings.ts default object
  2. Add UI in client/components/Pages/Main/Menu/
  3. Update docs/configuration.md settings table

Modify search behavior

  1. Edit client/modules/search.ts
  2. Update server/webSearchService.ts if server-side changes needed
  3. Check server/rerankerService.ts if reranking affected

Fix UI state issues

  1. Check PubSub channels in client/modules/pubSub.ts
  2. Verify component subscriptions in docs/ui-components.md
  3. Ensure proper state updates in business logic modules

Analyze test coverage

  1. Run npm run test:coverage to generate reports
  2. Check coverage/coverage-summary.json for quick metrics
  3. See docs/development-commands.md for full coverage analysis guide

Quality Gates

Before any change:

docker compose exec development-server npm run lint

This runs:

  • Biome (formatting/linting)
  • TypeScript (type checking)
  • knip (dead code detection)
  • jscpd (copy-paste detection)
  • Custom architectural linter
  • Doc gardening and documentation validator scripts

Agent-First Principles

Repository as System of Record:

  • All knowledge lives in versioned docs/ structure
  • This file is your entry point - start here
  • Follow links, don't assume - verify in code

Context Efficiency:

  • Use this map to navigate quickly
  • Return to this file when context drifts
  • Follow the decision tree for common tasks

Architecture & Boundaries:

  • Respect PubSub boundaries - don't cross concerns
  • Client vs server - keep them separate
  • Feature-based organization - one folder per feature

Documentation Maintenance:

  • Update these docs when you learn something new
  • Add cross-references when linking concepts
  • Keep examples current with actual code

Technology Stack

React + TypeScript + Mantine UI v9, with privacy-first architecture. See docs/core-technologies.md for complete dependency list and selection criteria.

Need Help?

  1. Check relevant doc in docs/
  2. Read the module code in client/modules/ or server/
  3. Look at similar existing implementations
  4. Run npm run lint to validate changes