# OpenVidu Meet - Copilot Instructions

## Project Overview

**OpenVidu Meet** is a production-ready videoconferencing application built on top of OpenVidu and LiveKit. It provides a complete, customizable solution for video conferencing with both Community Edition (CE) and Pro versions.

### Key Technologies
- **Frontend**: Angular 20.x, TypeScript, Angular Material
- **Backend**: Node.js, Express framework
- **Package Manager**: pnpm (v10.18.3+) with workspaces
- **Build System**: Nx-like monorepo structure
- **Testing**: Playwright (E2E), Jest (Unit)
- **Containerization**: Docker multi-stage builds

---

## Project Structure

```
openvidu-meet/
├── meet-ce/                          # Community Edition
│   ├── frontend/                     # Angular application
│   │   ├── src/                     # Main app source
│   │   ├── webcomponent/            # Web Component build
│   │   └── projects/
│   │       └── shared-meet-components/  # Shared Angular library
│   ├── backend/                      # Express backend
│   └── docker/                       # Docker configurations
├── meet-pro/                         # Pro Edition (extends CE)
├── testapp/                          # Testing application for E2E tests
├── meet-demo/                        # Demo application for showcasing features
├── scripts/                          # Build and automation scripts
└── meet.sh                           # Main CLI tool
```

---

## Architecture Principles

### 1. **Monorepo with External Dependencies**
- Uses pnpm workspaces for internal packages
- **External dependency**: `openvidu-components-angular` (located outside this repo)
- **Development**: Uses `workspace:*` protocol for local linking
- **CI/Docker**: Uses npm registry or tarball installations

### 2. **Dual Workspace Configuration**
```yaml
# Development (pnpm-workspace.yaml)
packages:
  - 'meet-ce/**'
  - '../openvidu/openvidu-components-angular/projects/openvidu-components-angular'

# CI/Docker (pnpm-workspace.docker.yaml)
packages:
  - 'meet-ce/**'  # No external packages
```

### 3. **Library Structure**
- `@openvidu-meet/frontend`: Main Angular application
- `@openvidu-meet/shared-components`: Reusable Angular library
  - Has `openvidu-components-angular` as **peerDependency**
  - Built as Angular library (ng-packagr)
  - Does NOT bundle dependencies

---

## Coding Standards

### TypeScript/Angular

```typescript
// ✅ Good: Use interfaces for data models
export interface Conference {
  id: string;
  name: string;
  participants: Participant[];
}

// ✅ Good: Use Angular dependency injection
@Injectable({ providedIn: 'root' })
export class ConferenceService {
  constructor(private http: HttpClient) {}
}

// ✅ Good: Use RxJS operators properly
this.participants$.pipe(
  map(participants => participants.filter(p => p.isActive)),
  takeUntil(this.destroy$)
).subscribe();

// ❌ Bad: Don't use 'any' type
// ❌ Bad: Don't forget to unsubscribe from observables
```

### Express Backend with TypeScript and InversifyJS

```typescript
// ✅ Good: Use decorators and dependency injection
@injectable()
export class LoggerService {
  log(message: string): void {
	console.log(message);
  }
}

```

---

## Build & Development

### Main CLI Tool: `meet.sh`

```bash
# Development
./meet.sh dev                        # Start development servers
./meet.sh dev --skip-install         # Skip dependency installation

# Building
./meet.sh build                      # Build all packages
./meet.sh build --skip-install       # Build without installing deps
./meet.sh build --base-href=/custom/ # Custom base href

# Docker
./meet.sh build-docker ov-meet       # Build Docker image (CE)
./meet.sh build-docker ov-meet --components-angular-version 3.5.0-beta1

# CI Preparation (Important!)
./meet.sh prepare-ci-build --components-angular-version 3.5.0-beta1
./meet.sh prepare-ci-build --components-angular-tarball ./components.tgz
./meet.sh restore-dev-config         # Restore development config
```

### CI/Docker Dependency Strategy

**Problem**: External package `openvidu-components-angular` is not in this repo.

**Solution**: Dual workspace configuration
1. **Development**: Uses `workspace:*` (local linking)
2. **CI/Docker**: Replaces `workspace:*` with registry/tarball versions

**Scripts**:
- `scripts/prepare-ci-build.sh`: Prepares workspace for CI/Docker builds
- `scripts/restore-dev-config.sh`: Restores development configuration

**Workflow**:
```bash
# Before CI/Docker build
prepare-ci-build.sh --components-angular-version 3.5.0-beta1
# Changes: pnpm-workspace.yaml → pnpm-workspace.docker.yaml
#          .npmrc → .npmrc.docker
#          package.json: workspace:* → ^3.5.0-beta1

# After build
restore-dev-config.sh
# Restores all original files
```

---

## Important Conventions

### 1. **Never Manually Edit package.json in CI**
```bash
# ❌ Bad: Manual sed in CI
sed -i 's/workspace:\*/3.5.0/g' package.json

# ✅ Good: Use prepare-ci-build script
./scripts/prepare-ci-build.sh --components-angular-version 3.5.0-beta1
```

### 2. **peerDependencies Guidelines**
- `shared-meet-components` declares `openvidu-components-angular` as **peerDependency**
- ✅ Use semver ranges: `"^3.0.0"`
- ✅ Use workspace protocol in dev: `"workspace:*"`
- ❌ NEVER use `file:` in peerDependencies (invalid)

### 3. **Angular Version Compatibility**
- Current: Angular 20.x
- `openvidu-components-angular` must support same Angular version
- Check peer dependency warnings carefully

### 4. **Docker Best Practices**
```dockerfile
# ✅ Good: Multi-stage build
FROM node:22.19.0 AS builder
# ... build stage ...
FROM node:22.19.0-alpine AS runner
# ... runtime stage ...

# ✅ Good: Use build args
ARG COMPONENTS_VERSION=3.5.0-beta1
ARG BASE_HREF=/

# ✅ Good: Use .dockerignore
# Avoid copying unnecessary files
```

---

## Common Tasks

### Adding a New Feature
1. Create feature in `meet-ce/frontend/src/app/features/`
2. If reusable, consider moving to `shared-meet-components`
3. Add tests in `*.spec.ts` files
4. Update documentation

### Updating openvidu-components-angular
```bash
# Development (local changes)
cd ../openvidu/openvidu-components-angular
npm run lib:build
cd -
pnpm install

# CI/Docker (version update)
./meet.sh prepare-ci-build --components-angular-version 3.5.0-beta1
./meet.sh build
./meet.sh restore-dev-config
```

### Working with Shared Components
```bash
# Build shared library
cd meet-ce/frontend/projects/shared-meet-components
ng build

# Use in main app
import { SomeComponent } from '@openvidu-meet/shared-components';
```

---

## Testing

### E2E Tests (Playwright)
```bash
npm run test:e2e              # Run all E2E tests
npm run test:e2e:ui           # Run with UI
npm run test:e2e:debug        # Debug mode
```

### Unit Tests (Jest)
```bash
npm run test                  # Run all unit tests
npm run test:watch            # Watch mode
npm run test:coverage         # With coverage
```

---

## Troubleshooting

### "workspace package not found" Error
**Cause**: Using `workspace:*` in CI/Docker mode

**Solution**:
```bash
./meet.sh prepare-ci-build --components-angular-version 3.5.0-beta1
```

### "Invalid peer dependency" Error
**Cause**: Using `file:` in peerDependencies

**Solution**: Use semver range (`^3.0.0`) in peerDependencies, not `file:` paths

### Angular Version Mismatch Warnings
**Cause**: `openvidu-components-angular` version doesn't support your Angular version

**Solution**: Update to compatible version
```bash
./meet.sh prepare-ci-build --components-angular-version 3.5.0-beta1  # Supports Angular 20
```

### pnpm-lock.yaml Conflicts
**Solution**: Restore development config first
```bash
./meet.sh restore-dev-config
pnpm install
```

---

## File Naming Conventions

```
✅ Good:
- conference.service.ts         (Services)
- conference.component.ts       (Components)
- conference.component.spec.ts  (Tests)
- conference.model.ts           (Models/Interfaces)
- conference.module.ts          (Modules)

❌ Bad:
- ConferenceService.ts          (PascalCase in filename)
- conference_service.ts         (snake_case)
- conferenceService.ts          (camelCase)
```

---

## Environment Variables

### Development
```bash
# Frontend
OPENVIDU_SERVER_URL=ws://localhost:4443
OPENVIDU_SECRET=MY_SECRET

# Backend
PORT=3000
OPENVIDU_URL=https://localhost:4443
OPENVIDU_SECRET=MY_SECRET
```

### Docker
Set via `docker-compose.yml` or Dockerfile ARG/ENV

---

## Security Considerations

1. **Never commit secrets** to version control
2. Use environment variables for sensitive data
3. Validate all user inputs (DTOs in backend)
4. Sanitize HTML content in frontend
5. Use Angular's built-in XSS protection

---

## Performance Guidelines

1. **Lazy load modules** when possible
2. **Use OnPush change detection** for performance-critical components
3. **Unsubscribe from observables** (use `takeUntil` or async pipe)
4. **Optimize Docker images** (multi-stage builds, alpine images)
5. **Use pnpm** for faster installs and efficient disk usage

---

## Documentation References

- Full CI/Docker strategy: `docs/ci-docker-dependencies-strategy.md`
- Dependency diagrams: `docs/ci-docker-dependencies-diagrams.md`
- Implementation summary: `docs/IMPLEMENTATION_SUMMARY.md`
- Validation checklist: `docs/VALIDATION_CHECKLIST.md`

---

## When Suggesting Code Changes

1. **Understand the context**: Is this for development or CI/Docker?
2. **Check package.json**: Are dependencies using `workspace:*` or versions?
3. **Consider peerDependencies**: Never use `file:` paths in peerDependencies
4. **Follow conventions**: Use existing patterns in the codebase
5. **Test implications**: Consider impact on both local dev and CI/Docker builds
6. **Use prepare-ci-build**: For any CI/Docker related changes

---

## Quick Reference Commands

```bash
# Development
./meet.sh dev                                    # Start dev servers
./meet.sh build                                  # Build all

# CI/Docker
./meet.sh prepare-ci-build --components-angular-version 3.5.0-beta1
./meet.sh build-docker ov-meet
./meet.sh restore-dev-config

# Testing
npm run test                                     # Unit tests
npm run test:e2e                                 # E2E tests

# Package management
pnpm install                                     # Install deps
pnpm add <package> --filter @openvidu-meet/frontend  # Add to specific package
```

---

## Remember

- **Always use scripts** for CI/Docker preparation, never manual edits
- **peerDependencies** are for library compatibility declarations, not installation
- **workspace:*** works only when package is in workspace
- **Test locally** before pushing CI/Docker changes
- **Document breaking changes** and update this file accordingly

---

**Last Updated**: 2025-10-27
**Project Version**: OpenVidu Meet CE/Pro
**Maintained By**: OpenVidu Team