CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Overview
6 
7Chat UI is a SvelteKit application that provides a chat interface for LLMs. It powers HuggingChat (hf.co/chat). The app speaks exclusively to OpenAI-compatible APIs via `OPENAI_BASE_URL`.
8 
9## Commands
10 
11```bash
12npm run dev          # Start dev server on localhost:5173
13npm run build        # Production build
14npm run preview      # Preview production build
15npm run check        # TypeScript validation (svelte-kit sync + svelte-check)
16npm run lint         # Check formatting (Prettier) and linting (ESLint)
17npm run format       # Auto-format with Prettier
18npm run test         # Run all tests (Vitest)
19```
20 
21### Running a Single Test
22 
23```bash
24npx vitest run path/to/file.spec.ts        # Run specific test file
25npx vitest run -t "test name"              # Run test by name
26npx vitest --watch path/to/file.spec.ts    # Watch mode for single file
27```
28 
29### Test Environments
30 
31Tests are split into three workspaces (configured in vite.config.ts):
32 
33- **Client tests** (`*.svelte.test.ts`): Browser environment with Playwright
34- **SSR tests** (`*.ssr.test.ts`): Node environment for server-side rendering
35- **Server tests** (`*.test.ts`, `*.spec.ts`): Node environment for utilities
36 
37## Architecture
38 
39### Stack
40 
41- **SvelteKit 2** with Svelte 5 (uses runes: `$state`, `$effect`, `$bindable`)
42- **MongoDB** for persistence (auto-fallback to in-memory with MongoMemoryServer when `MONGODB_URL` not set)
43- **TailwindCSS** for styling
44 
45### Key Directories
46 
47```
48src/
49├── lib/
50│   ├── components/       # Svelte components (chat/, mcp/, voice/, icons/)
51│   ├── server/
52│   │   ├── api/utils/       # Shared API helpers (auth, superjson, model/conversation resolvers)
53│   │   ├── textGeneration/  # LLM streaming pipeline
54│   │   ├── mcp/          # Model Context Protocol integration
55│   │   ├── router/       # Smart model routing (Omni)
56│   │   ├── database.ts   # MongoDB collections
57│   │   ├── models.ts     # Model registry from OPENAI_BASE_URL/models
58│   │   └── auth.ts       # OpenID Connect authentication
59│   ├── types/            # TypeScript interfaces (Conversation, Message, User, Model, etc.)
60│   ├── stores/           # Svelte stores for reactive state
61│   └── utils/            # Helpers (tree/, marked.ts, auth.ts, etc.)
62├── routes/               # SvelteKit file-based routing
63│   ├── conversation/[id]/  # Chat page + streaming endpoint
64│   ├── settings/         # User settings pages
65│   ├── api/              # Legacy v1 API endpoints (mcp, transcribe, fetch-url)
66│   ├── api/v2/           # REST API endpoints (+server.ts)
67│   └── r/[id]/           # Shared conversation view
68```
69 
70### Text Generation Flow
71 
721. User sends message via `POST /conversation/[id]`
732. Server validates user, fetches conversation history
743. Builds message tree structure (see `src/lib/utils/tree/`)
754. Calls LLM endpoint via OpenAI client
765. Streams response back, stores in MongoDB
77 
78### Model Context Protocol (MCP)
79 
80MCP servers are configured via `MCP_SERVERS` env var. When enabled, tools are exposed as OpenAI function calls. The router can auto-select tools-capable models when `LLM_ROUTER_ENABLE_TOOLS=true`.
81 
82### LLM Router (Omni)
83 
84Smart routing via Arch-Router model. Configured with:
85 
86- `LLM_ROUTER_ROUTES_PATH`: JSON file defining routes
87- `LLM_ROUTER_ARCH_BASE_URL`: Router endpoint
88- Shortcuts: multimodal routes bypass router if `LLM_ROUTER_ENABLE_MULTIMODAL=true`
89 
90### Database Collections
91 
92- `conversations` - Chat sessions with nested messages
93- `users` - User accounts (OIDC-backed)
94- `sessions` - Session data
95- `sharedConversations` - Public share links
96- `settings` - User preferences
97 
98## Environment Setup
99 
100Copy `.env` to `.env.local` and configure:
101 
102```env
103OPENAI_BASE_URL=https://router.huggingface.co/v1
104OPENAI_API_KEY=hf_***
105# MONGODB_URL is optional; omit for in-memory DB persisted to ./db
106```
107 
108See `.env` for full list of variables including router config, MCP servers, auth, and feature flags.
109 
110## Code Conventions
111 
112- TypeScript strict mode enabled
113- ESLint: no `any`, no non-null assertions
114- Prettier: tabs, 100 char width, Tailwind class sorting
115- Server vs client separation via SvelteKit conventions (`+page.server.ts` vs `+page.ts`)
116 
117## Feature Development Checklist
118 
119When building new features, consider:
120 
1211. **HuggingChat vs self-hosted**: Wrap HuggingChat-specific features with `publicConfig.isHuggingChat`
1222. **Settings persistence**: Add new fields to `src/lib/types/Settings.ts`, update API endpoint at `src/routes/api/v2/user/settings/+server.ts`
1233. **Rich dropdowns**: Use `bits-ui` (Select, DropdownMenu) instead of native elements when you need icons/images in options
1244. **Scrollbars**: Use `scrollbar-custom` class for styled scrollbars
1255. **Icons**: Custom icons in `$lib/components/icons/`, use Carbon (`~icons/carbon/*`) or Lucide (`~icons/lucide/*`) for standard icons
1266. **Provider avatars**: Use `PROVIDERS_HUB_ORGS` from `@huggingface/inference` for HF provider avatar URLs
127