Spaces:
Running
Running
File size: 2,554 Bytes
16b7924 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 |
# 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`
|