# CLAUDE.md

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

## Overview

Jicofo (JItsi COnference FOcus) is a signaling server for Jitsi Meet conferences. It manages XMPP Multi-User Chat (MUC) rooms, initiates Jingle sessions with participants, and coordinates media routing through Jitsi Videobridge instances using the Colibri2 protocol.

## Build and Test Commands

### Building
```bash
mvn install                          # Build all modules and create distribution package
mvn clean install                    # Clean build
mvn install -DskipTests              # Build without running tests
```

The distribution package is created in `jicofo/target/jicofo-1.1-SNAPSHOT-archive.zip`.

### Testing
```bash
mvn test                             # Run all tests
mvn test -pl jicofo-selector         # Run tests for specific module
mvn test -Dtest=BridgeSelectorTest   # Run specific test class
```

### Code Quality
```bash
mvn exec:exec@ktlint-check           # Run ktlint (must be run for individual modules e.g. in ./jicofo-selector/; sibling modules must
                                     # be resolvable, so run "mvn install -DskipTests" from the root first if they are not)
mvn exec:exec@ktlint-format          # Auto-format Kotlin code with ktlint (same restriction)
mvn checkstyle:check                 # Run checkstyle (config: checkstyle.xml)
```

## Architecture

### Module Structure

This is a multi-module Maven project with three modules:

1. **jicofo-common** - Shared utilities and data structures
   - Conference source management (`ConferenceSourceMap`, `EndpointSourceSet`, `Source`)
   - XMPP/MUC abstractions (`ChatRoom`, `ChatRoomMember`, `BaseBrewery`)
   - Codec management
   - Metrics infrastructure
   - No dependencies on other jicofo modules

2. **jicofo-selector** - Bridge selection and Colibri session management
   - Self-contained, reusable component for bridge selection logic
   - Bridge management (`Bridge`, `BridgeSelector`, `BridgeMucDetector`)
   - Pluggable selection strategies:
     - `SingleBridgeSelectionStrategy` - Single bridge, no Octo
     - `RegionBasedBridgeSelectionStrategy` - Geographic distribution with Octo
     - `IntraRegionBridgeSelectionStrategy` - Load-balanced Octo within regions
     - `VisitorSelectionStrategy` - Separate strategies for visitors vs participants
   - Colibri2 session management (`ColibriV2SessionManager`, `Colibri2Session`)
   - Depends only on jicofo-common

3. **jicofo** - Main application module
   - Entry point: `Main.java`
   - Service orchestration: `JicofoServices.kt` (creates and manages all services)
   - Conference management: `JitsiMeetConferenceImpl` (Java, ~2000+ lines, core conference logic)
   - Focus management: `FocusManager` (conference lifecycle, room JID mapping)
   - XMPP services: `XmppServices`, `XmppProvider`, modular IQ handlers
   - Authentication: `AbstractAuthAuthority`, `XMPPDomainAuthAuthority`, `ExternalJWTAuthority`
   - External service integration: Jibri (recording/streaming), Jigasi (SIP gateway)
   - REST API: Ktor-based HTTP interface for health checks, stats, debug endpoints
   - Depends on both jicofo-common and jicofo-selector

### Key Components & Responsibilities

**Conference Management**
- `JitsiMeetConferenceImpl` - Main conference implementation (manages Jingle sessions, coordinates with bridges, handles MUC membership, lifecycle management)
- `Participant` - Represents a conference participant with Jingle session, sources, and bridge allocation
- `ParticipantInviteRunnable` - Handles participant invitation flow (Jingle session establishment)
- `FocusManager` - Conference lifecycle management, maps room JIDs to conference instances

**Bridge Selection**
- `BridgeSelector` - Core component for selecting optimal bridges based on health, stress, operational status, and configured strategy
- `Bridge` - Represents a single jitsi-videobridge instance with health and stress tracking
- `BridgeMucDetector` - Discovers bridges via XMPP MUC (brewery pattern)
- `JvbDoctor` - Health check management for bridges

**Colibri Session Management**
- `ColibriV2SessionManager` - Manages Colibri2 sessions with bridges
- `Colibri2Session` - Represents a session with a single bridge
- Sends `ConferenceModifyIQ` to bridges for allocations and updates

**XMPP Handling**
- `XmppProvider` - Manages multiple XMPP connections (client, service, visitor)
- Modular IQ handlers: `ConferenceIqHandler`, `JingleIqRequestHandler`, `JibriIqHandler`, etc.
- `VisitorsManager` - Manages visitor functionality across multiple XMPP nodes

### Application Flow

1. **Startup**: `Main.java` loads config, creates `JicofoServices`, sets up signal handlers
2. **Conference Creation**: Client requests conference → `FocusManager.conferenceRequest()` → `JitsiMeetConferenceImpl.start()`
3. **Participant Join**: Participant joins MUC → conference detects new member → `ParticipantInviteRunnable` selects bridge, allocates Colibri endpoint, sends Jingle session-initiate
4. **Bridge Selection**: Considers operational status, stress level, graceful shutdown status, version compatibility, and selection strategy
5. **Media Flow**: Participant accepts Jingle session, media flows through videobridge

### Configuration

Configuration uses HOCON format (lightbend/config). Main config file is typically `/etc/jitsi/jicofo/jicofo.conf`.

Reference configuration with all available options: `jicofo-selector/src/main/resources/reference.conf`

Configuration objects in code are typically Kotlin companion objects (e.g., `BridgeConfig.config`, `ConferenceConfig.config`).

### Language & Conventions

- **Kotlin**: New code, utilities, data structures, all test code
- **Java**: Legacy code, notably `JitsiMeetConferenceImpl` (complex conference management)
- **Interop**: Seamless with `@JvmOverloads`, `@JvmField`, companion objects

### Testing Framework

- **Primary**: Kotest (BDD-style specs with `ShouldSpec`)
- **Style**: `context("...") { should("...") { ... } }` for behavior-driven tests
- **Mocking**: MockK for Kotlin (`mockk { every { ... } returns ... }`)
- **Test Utilities**: Mock implementations in `jicofo/src/test/kotlin/org/jitsi/jicofo/mock/`
  - `MockXmppConnection`, `MockXmppProvider` - XMPP testing
  - `MockChatRoom` - MUC simulation
  - `TestColibri2Server` - Colibri2 protocol testing
- **Configuration Testing**: Use `withNewConfig { ... }` helper for custom configs
- **Time Control**: `FakeClock` for time-dependent tests
- **Isolation**: Tests use `IsolationMode.InstancePerLeaf` for test isolation
- **Location**: Tests mirror source structure (`src/test/kotlin` matches `src/main/kotlin`)

### Important Architectural Patterns

**Separation of Concerns**: Clear module boundaries (common utilities, bridge selection logic, application orchestration)

**Dependency Injection via Constructor**: Services are composed via constructor injection in `JicofoServices.kt`

**Strategy Pattern**: Bridge selection strategies and topology strategies are pluggable, configured via HOCON

**Observer Pattern**: Event-driven architecture with `AsyncEventEmitter` (e.g., `BridgeSelector.EventHandler`, `ColibriSessionManager.Listener`)

**Thread Safety**: Extensive use of `synchronized` blocks, `ConferenceSourceMap` uses `ConcurrentHashMap`, careful lock ordering to prevent deadlocks

**Metrics & Observability**: Centralized metrics via `JicofoMetricsContainer`, periodic metric updates, debug state endpoints (`debugState` properties)

### Key Protocols

**XMPP**: Communication backbone with multiple connections (Client for participants, Service for bridges, Visitor for visitor nodes)

**Jingle**: Standard XMPP protocol for peer-to-peer session negotiation (jicofo terminates Jingle signaling, not media)

**Colibri2**: Modern protocol for bridge communication (endpoint allocation, management, relay support for Octo)

**Brewery Pattern**: Service discovery - bridges/Jibris/Jigasis join specific MUC rooms, jicofo monitors presence

### Notable Design Decisions

- **Graceful Degradation**: Bridges report stress levels, can enter graceful shutdown, health checks with timeout-based recovery
- **Scalability**: Multi-bridge support (Octo mesh), region-based selection, visitor architecture for large conferences, load redistribution
- **Singleton with Synchronization**: `JicofoServices` uses synchronized singleton pattern (required because services start threads that depend on the singleton)
- **Legacy Code Preservation**: `JitsiMeetConferenceImpl` remains in Java with extensive synchronization (noted as needing refactoring, but stable)