# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Context

This is a **HealthChat** fork of Element Web (a Matrix client built with React and TypeScript). HealthChat customizations are primarily configuration-based: custom branding, homeserver (matrix.healthchat.ch), SSO auto-redirect, and many advanced features disabled for a simplified UX. The `release/healthchat` branch is the main working branch; `master` tracks upstream.

## Prerequisites

- Node.js >= 22.18
- Yarn 1.x (classic)

## Commands

### Setup
- `yarn install` - Install dependencies (also runs `postinstall` which applies patches via patch-package)
- Copy `config.sample.json` to `config.json` and configure (see docs/config.md)

### Development
- `yarn start` - Run development server on http://localhost:8080
- `yarn start:https` - Run development server with HTTPS
- `yarn build` - Production build (outputs to webapp/)
- `yarn dist` - Create distribution tarball

**Linux note**: If builds fail silently or with `EMFILE: too many open files`, increase inotify limits:
```bash
sudo sysctl fs.inotify.max_user_watches=131072
sudo sysctl fs.inotify.max_user_instances=512
```

### Testing
- `yarn test` - Run Jest unit tests
- `yarn test:playwright` - Run Playwright e2e tests
- `yarn test:playwright:open` - Open Playwright test UI
- `yarn coverage` - Run tests with coverage reporting

To run a single test file:
- `yarn test path/to/test-file-test.ts` (note: test files use `-test.ts` suffix, not `.test.ts`)
- `yarn test:playwright path/to/e2e-test.ts`

### Code Quality
- `yarn lint` - Run all linters (TypeScript, ESLint, Stylelint)
- `yarn lint:js-fix` - Auto-fix ESLint issues (runs Prettier + ESLint)
- `yarn lint:types` - TypeScript type checking only
- `yarn lint:style` - Check CSS/PostCSS styles

### Utilities
- `yarn make-component` - Scaffold new React component
- `yarn i18n` - Manage translations
- `yarn storybook` - Run Storybook on port 6007

## Architecture

### Component Structure
The application follows a hierarchical component structure:
- `MatrixChat` - Root component managing the entire application state
- `LeftPanel` - Room list, spaces, and navigation
- `MainSplit` - Central room view with messages and input
- `RightPanel` - Member list, room info, and contextual panels

Components are organized in `src/components/`:
- `structures/` - Major layout components (use class components)
- `views/` - Reusable UI components grouped by function (auth, dialogs, messages, rooms, settings)

### Monorepo Structure
- `packages/shared-components/` - Separate package (`@element-hq/web-shared-components`) with its own build (Vite), tests, and Storybook. Contains shared UI components (audio, avatar, composer, event-tiles, message-body).

### State Management
Uses Flux architecture with:
- Centralized dispatcher in `src/dispatcher/`
- Stores in `src/stores/` as singletons (access via `FooStore.instance`)
- Dispatch actions: `dis.dispatch({ action: Action.FOO, ...payload })` or `dis.fire(Action.FOO)` for action-only

### Styling
- PostCSS files with `.pcss` extension, located in `res/css/` (not co-located with components)
- CSS file must match component name: `res/css/views/rooms/_MessageTile.pcss` for `src/components/views/rooms/MessageTile.tsx`
- BEM-like naming: `mx_ComponentName_element`
- Theming via CSS custom properties
- Use `$font` variables, not manual font sizes
- Document z-index values, pixel adjustments with comments explaining why

### Matrix Integration
- Uses `matrix-js-sdk` for all Matrix protocol operations
- Client instance accessed via `MatrixClientPeg`
- Room and event handling through SDK abstractions

### Module System
Plugin architecture in `src/modules/` and `module_system/`:
- Allows runtime extension of functionality
- Module API for registering custom components and handlers
- Build step: `yarn build:module_system`

### Testing Patterns
- Unit tests in `test/unit-tests/` mirroring `src/` structure, using Jest
- **Test file naming**: `*-test.[tj]s?(x)` (hyphenated, NOT `.test.ts`)
- E2E tests in `playwright/e2e/` using Playwright with page object models in `playwright/pages/`
- Mock Matrix client and SDK extensively in tests
- Use `jest-matrix-react` for component rendering (NOT `@testing-library/react`)
- Test convention: `describe("ComponentName", () => { it("should ...", () => { ... }); });`

### Important Conventions
- TypeScript strict mode - always use explicit types, describe types exhaustively
- Functional components with hooks preferred over class components (except "structures" which use classes)
- Translations use `_t()` function with hierarchical keys
- 4-space indentation, 120 character line limit, double quotes, Prettier-formatted
- Component files: UpperCamelCase, utilities: kebab-case
- Use named exports, one component per file
- Use `Optional<T>` type instead of truly optional parameters when callers should explicitly acknowledge missing values
- CSS class names must be prefixed with `mx_` and match component name (e.g., `mx_RoomTile`)
- Import matrix-js-sdk via `matrix-js-sdk/src/matrix` only (not `matrix-js-sdk` or `matrix-js-sdk/src`)
- No `React.forwardRef` - use ref props directly instead
- Use UIStore for window dimensions instead of `window.innerHeight`/`window.innerWidth`
- Use Media helper for MXC URL handling instead of direct `mxcUrlToHttp` calls
- `eslint-ignore` / `@ts-ignore` must have a comment explaining why
- Prefer async/await over promise chaining
- Interfaces for object definitions, types for union/parameter-value-only declarations
- Interface properties terminated with semicolons, not commas

### Linked Development with matrix-js-sdk
For developing against local SDK changes:
```bash
# In matrix-js-sdk directory
yarn link && yarn install

# In element-web directory
yarn link matrix-js-sdk && yarn install && yarn start
```