openvidu/.github/workflows/.copilot-instructions.md

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

# 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

// ✅ 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

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

---

Build & Development

Main CLI Tool: meet.sh

# 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:

# 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

# ❌ 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

# ✅ 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

# 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

# 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)

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)

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:

./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

./meet.sh prepare-ci-build --components-angular-version 3.5.0-beta1  # Supports Angular 20

pnpm-lock.yaml Conflicts

Solution: Restore development config first

./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

# 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

# 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