add copilot instructions documentation for OpenVidu Meet project
This commit is contained in:
Carlos Santos
parent
ed4e336473
commit
4b9c5dbdd1
397
.github/workflows/.copilot-instructions.md
vendored
Normal file
397
.github/workflows/.copilot-instructions.md
vendored
Normal file
@ -0,0 +1,397 @@
|
|||||||
|
# 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
|
||||||
Loading…
x
Reference in New Issue
Block a user