healthchat-web/CLAUDE.md

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:

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:

# In matrix-js-sdk directory
yarn link && yarn install

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