agents.md

# Repository Guidelines

## Project Structure

- **`client/`**: Frontend React application
  - **`components/`**: Feature-based UI components (`Search`, `AiResponse`, `Analytics`). Each folder is self-contained with related styles, hooks, and utilities.
  - **`modules/`**: Core business logic (PubSub stores, search services, database layers)
  - **`hooks/`**: Custom React hooks
  - **`public/`**: Static assets
- **`server/`**: Server hooks for search endpoints, caching, compression, CORS, and API validation
- **`shared/`**: Utilities shared between client and server
- **`vite.config.ts`**: Build and server configuration with environment-driven feature flags

## Development Commands

- **`npm run dev`**: Start development server with HMR
- **`npm run build`**: Compile for production
- **`npm run start`**: Preview production build
- **`npm run lint`**: Check code quality (Biome, TypeScript, dependencies)
- **`npm run format`**: Auto-format code with Biome

## Coding Conventions

**Tech Stack**: React + TypeScript + Mantine UI (`@mantine/core`, `@mantine/hooks`, `@mantine/form`)

**Style**:

- Run `npm run format` before committing (enforced via `husky` and `lint-staged`)
- Named function exports: `export function ComponentName` (not `React.FC`)
- Use `React.lazy()` for route-level components
- PascalCase for components/types, camelCase for functions/variables, UPPER_SNAKE_CASE for constants

**TypeScript**:

- Use interfaces for data structures
- Avoid comments; use TSDoc only for public APIs

**State & Imports**:

- Use `create-pubsub` for global state (avoid nested context providers)
- Prefer absolute path aliases where configured

**UI & Performance**:

- Use Mantine components for consistency
- Ensure keyboard navigation, ARIA labels, semantic HTML
- Use `React.memo()` and `useCallback()` for optimization

## Pull Requests

- Ensure `npm run lint` pass
- Keep PRs focused on a single feature or fix
- Include clear descriptions and screenshots for UI changes
- Write descriptive commit messages

## Architecture

- **Privacy-First**: Local storage via Dexie.js (IndexedDB)
- **AI Inference**: Server-side (OpenAI, Horde) and client-side (WebLLM, Wllama)
- **State Management**: PubSub pattern for decoupled state (no prop drilling)
- **Search Pipeline**: Server hooks handle validation, caching, compression, reranking

## Configuration

- **Environment**: See `.env.example` for options
- **Docker Development**: `docker compose up`
- **Docker Production**: `docker compose -f docker-compose.production.yml up --build`