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