docs/coding-conventions.md

Coding Conventions

Tech Stack

React 19 + TypeScript + Mantine UI v9 (@mantine/core, @mantine/hooks, @mantine/form, @mantine/notifications, @mantine/code-highlight, @mantine/carousel)

• Build Tool: Vite 8
• Linting/Formatting: Biome 2
• Testing: Vitest 5 + Testing Library
• State Management: create-pubsub
• Routing: Wouter 3
• AI Integration: Wllama, OpenAI-compatible APIs
• Search: SearXNG integration
• Package Manager: npm

Style Guidelines

• Run npm run lint before committing (enforced via husky)
• Use Biome for formatting and linting (replaces ESLint/Prettier)
• 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
• Double quotes for strings (Biome default)
• 2-space indentation (Biome default)

TypeScript

• Use interfaces for data structures
• Avoid comments; use TSDoc only for public APIs
• Strict mode enabled - no any types
• React 19 types with strict TypeScript checking
• Path aliases configured: @/ (client root), @/modules, @/components, @/hooks, @shared, @root

State & Imports

• Use create-pubsub for global state (avoid nested context providers)
• Prefer absolute path aliases where configured (@/ for client root)

UI & Performance

• Use Mantine v9 components for consistency
• Ensure keyboard navigation, ARIA labels, semantic HTML
• Use React.memo() and useCallback() for optimization
• Lazy loading with Vite's dynamic imports
• Bundle analysis with rollup-plugin-visualizer
• WebGPU detection for optimal AI inference

File Organization

• Components organized by feature domain in client/components/
• Each component folder is self-contained
• Business logic modules in client/modules/
• Hooks in dedicated client/hooks/
• Server-side code in server/
• Shared types and utilities in shared/
• Test files co-located with .test.ts suffix

Testing

• Vitest for unit/integration tests
• Testing Library for component testing
• Coverage reports with npm run test:coverage
• Test files use .test.ts suffix
• Mock files in client/modules/testUtils.ts

Documentation

• Do not cite line numbers in docs (for example, file.ts#123-456). The ranges go stale when the source moves. Name the symbol instead, and keep a file path only when it is the only locator for what the sentence describes.

Related Topics

• Project Structure: docs/project-structure.md - Directory organization
• Design: docs/design.md - UI/UX principles
• UI Components: docs/ui-components.md - Component architecture
• Pull Requests: docs/pull-requests.md - Contribution workflow