|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +Jitsi Test Lab is a React-based testing application for Jitsi Meet and Jitsi as a Service (JaaS). It provides manual testing capabilities, JWT token generation, webhook monitoring, and configuration management for developers working with Jitsi video conferencing solutions. |
| 8 | + |
| 9 | +## Development Commands |
| 10 | + |
| 11 | +```bash |
| 12 | +npm run dev # Start Vite development server (port 5173) |
| 13 | +npm run build # Build for production |
| 14 | +npm run lint # Run ESLint code checking |
| 15 | +npm run preview # Preview production build |
| 16 | +``` |
| 17 | + |
| 18 | +For full development environment with WebSocket proxy: |
| 19 | +```bash |
| 20 | +./start-dev.sh # Starts both WebSocket proxy (port 8080) and React dev server |
| 21 | +``` |
| 22 | + |
| 23 | +Note: The WebSocket proxy (`websocket-proxy.js`) runs on port 8080 and bridges connections between the browser and remote JaaS webhook proxy servers. |
| 24 | + |
| 25 | +## Architecture Overview |
| 26 | + |
| 27 | +**Tech Stack:** |
| 28 | +- React 19.1.1 with TypeScript |
| 29 | +- Material-UI (MUI) 7.3.1 for components |
| 30 | +- Vite 7.1.2 for build tooling |
| 31 | +- JOSE library for JWT token handling |
| 32 | +- WebSocket proxy server for webhook testing |
| 33 | + |
| 34 | +**Key Components Structure:** |
| 35 | +- `src/components/IFrameControlPage.tsx` - Jitsi Meet iframe controls |
| 36 | +- `src/components/JaaSConfigPage.tsx` - JaaS configuration management |
| 37 | +- `src/components/TokensPage.tsx` - JWT token generation for JaaS |
| 38 | +- `src/components/WebhooksPage.tsx` - Webhook testing interface |
| 39 | +- `src/components/SettingsPage.tsx` - Application settings |
| 40 | +- `token.ts` - JWT token generation logic (root level) |
| 41 | +- `websocket-proxy.js` - Local WebSocket proxy server (root level) |
| 42 | + |
| 43 | +**Configuration System:** |
| 44 | +- `public/config.json` - Public configuration presets (exposed to users) |
| 45 | +- `src/config.ts` - Configuration loading logic |
| 46 | +- Local storage for user-specific settings |
| 47 | +- Runtime configuration updates supported |
| 48 | + |
| 49 | +## Development Workflow |
| 50 | + |
| 51 | +**WebSocket Proxy Integration:** |
| 52 | +The application includes a local WebSocket proxy server that handles authentication headers for JaaS webhook connections. The proxy: |
| 53 | +1. Accepts connections from browsers (which can't send auth headers) |
| 54 | +2. Establishes authenticated connections to remote webhook proxies |
| 55 | +3. Bridges messages between browser and remote servers |
| 56 | + |
| 57 | +**JaaS Integration:** |
| 58 | +- JWT token generation using private keys via JOSE library |
| 59 | +- Tenant configuration (vpaas-magic-cookie-* format) |
| 60 | +- API key integration with kid parameter |
| 61 | +- Webhook shared secret management |
| 62 | + |
| 63 | +**Security Notes:** |
| 64 | +- `public/config.json` is intentionally exposed - never include private keys |
| 65 | +- Private keys should only be used with dedicated testing accounts |
| 66 | +- Local storage handles sensitive configuration in browser |
| 67 | + |
| 68 | +## Docker Deployment |
| 69 | + |
| 70 | +Multi-stage Docker build process: |
| 71 | +- Build stage uses Node.js 20 Alpine |
| 72 | +- Production stage uses Nginx Alpine |
| 73 | +- Automatic Docker Hub publishing via GitHub Actions |
| 74 | +- Support for custom config.json via volume mounts |
| 75 | + |
| 76 | +## Testing Integration |
| 77 | + |
| 78 | +The application integrates with external webhook testing via: |
| 79 | +- `jaas-test-wh-proxy` deployment required for webhook testing |
| 80 | +- WebSocket connection to proxy servers |
| 81 | +- Real-time webhook event monitoring |
| 82 | +- Shared secret authentication for webhook security |
0 commit comments