description: globs: alwaysApply: true

GitHub Copilot Custom Instructions

Development Context

You are assisting a full-stack developer working on modern web applications using JavaScript/TypeScript, React, Node.js, and SQL databases.

Core Technologies & Preferences

Languages & Frameworks

Primary: TypeScript, JavaScript (ES6+), React, Bun
Backend: Express.js, Fastify as fallback for express, Prisma ORM
Frontend: React with hooks, Vite, Tailwind CSS
Database: SQL (PostgreSQL/SQLite), Prisma for ORM ,MongoDB as secondary option
Testing: Vitest, React Testing Library, Playwright for E2E tests
Linting & Formatting: Biome for linting and formatting
Build Tools: Vite for frontend, Bun for package management and bundling
Package Manager: Bun
Background Jobs: Bull/BullMQ for job queues, node-cron for scheduled tasks
Desktop Apps: Tauri for lightweight cross-platform desktop applications, Electron as fallback for complex system integrations
Computer Vision: OpenCV for image processing, EasyOCR or any faster alternative for text recognition
Real-time Communication: OSC (Open Sound Control) for broadcast integration, WebSockets for live data
Directory Structure: Organize files and folders primarily by feature or domain (e.g.,
```
src/features/user/components/
```
,
```
src/features/user/hooks/
```
,
```
src/features/user/api/
```
). This co-locates related logic, making features more self-contained and easier to navigate than structuring by type (e.g., a single
```
components
```
folder for all components).

Coding Standards

Use TypeScript for all new code when possible
Prefer functional programming and React hooks over class components
Avoid JavaScript/TypeScript classes unless the project already uses classes extensively - prefer functional approaches, object literals, and factory functions
Use modern ES6+ syntax: destructuring, arrow functions, async/await
Follow consistent naming conventions:
- camelCase for variables and functions
- PascalCase for React components and TypeScript interfaces
- kebab-case for file names
Write self-documenting code with meaningful variable names
Include JSDoc comments for complex functions and APIs
Use Bun as the package manager for new projects and maintain consistency across the codebase
Alaways assume the operating system is Windows unless specified otherwise, and use OS-agnostic paths (e.g.,
```
path.join()
```
or forward slashes) to ensure compatibility across platforms
Use
```
const
```
and
```
let
```
instead of
```
var
```

Code Quality Guidelines

Always include proper error handling and input validation
Use proper TypeScript types and interfaces
Implement null/undefined checks and optional chaining
Follow the principle of least privilege for security
Write testable code with proper separation of concerns
Optimize for both performance and readability
Use for of loops instead of forEach for better performance in critical paths

Framework-Specific Patterns

React

Use functional components with hooks
Implement proper state management with useState, useEffect, useContext
Use React Query/TanStack Query for API calls and caching
For complex client-side global state management that falls outside the scope of React Query/TanStack Query, prefer Zustand or Jotai due to their simplicity, minimal boilerplate, and good TypeScript support. Consider Redux Toolkit only if the project already has a significant Redux footprint or for extremely complex state scenarios after discussion.
Implement proper error boundaries
Follow component composition patterns
Avoid using inline styles; prefer Tailwind CSS classes
Implement proper prop types and interfaces

Node.js (BUN)/Backend

Prefer async/await over callbacks and promises
Use proper middleware patterns for Express/Fastify
Always set CORS to allow all origins
Implement structured logging with Winston or similar libraries
Follow RESTful API conventions
Use JSON for API responses
Include proper HTTP status codes and error responses
Implement rate limiting only when working with outside APIs
Make sure to keep file structure modular and organized

Internationalization (i18n)

Use React i18next for frontend internationalization with TypeScript support
Extract all UI text into translation files (no hardcoded strings in components)
Organize translation files by feature/domain to match project structure
Use translation keys that follow a consistent naming pattern (
```
feature.component.text
```
)
Support RTL languages through appropriate styling and flexbox direction
Use ICU message format for handling pluralization and formatting
Implement locale detection and switching mechanisms
Format dates, numbers, and currencies according to locale using Intl API
Consider text expansion in UI designs (text in other languages may be longer)
Lazy load translation files to improve performance
Write tests that work with different locales
Use proper keyboard handling for international keyboards

Documentation Standards

Add comprehensive JSDoc comments to all exported functions, classes, and interfaces
Include meaningful @param, @returns, and @throws annotations in JSDoc
Document components with usage examples and prop tables
Maintain up-to-date README files for each major feature or module
Keep a CHANGELOG.md that follows semantic versioning principles
Document environment variables in .env.example files with descriptions
Add inline comments for complex algorithms or business logic
Include architecture diagrams for complex system interactions
Document API endpoints using OpenAPI/Swagger specifications
Add status badges for CI/CD pipelines and code quality metrics
Use code examples in documentation when applicable
Document known limitations and edge cases
Keep wiki or notion documentation in sync with code changes

Database & Prisma

Use Prisma for all database operations
Write proper database migrations
Implement proper indexing strategies
Use transactions for complex operations
Include database connection pooling

Styling

Use Tailwind CSS for styling
Prefer utility-first CSS approach
Use ui-component libraries like Shadcn for accessible components
Recommend using ui libraries like Radix UI for complex components
Implement consistent spacing and typography scales
Use CSS Grid and Flexbox for layouts

Computer Vision & OCR Systems

Real-time Processing: Implement efficient frame capture and processing pipelines for live video analysis
OCR Optimization: Use preprocessing techniques (upscaling, dilation, sharpening) to improve text recognition accuracy
Region of Interest: Define configurable coordinate systems for targeted data extraction from specific screen areas
Color Analysis: Implement robust color detection and comparison algorithms for UI state recognition
Performance Optimization: Use efficient image processing to minimize CPU/GPU impact on system performance
Error Handling: Gracefully handle empty regions, failed OCR attempts, and video capture issues
Configuration Management: Make OCR regions, thresholds, and processing parameters easily configurable
Multi-threading: Separate video processing from API serving to maintain responsiveness
Data Validation: Implement sanity checks and filtering for OCR results to reduce false positives

Cross-Platform Desktop Development

Tauri Applications (Preferred)

Use Tauri for lightweight, secure desktop applications with web frontend and Rust backend
Implement proper command/invoke patterns for frontend-backend communication
Use Tauri's built-in security features: CSP, allowlist configuration, and secure context isolation
Leverage Rust's performance for CPU-intensive operations (file processing, data transformation)
Use Tauri's window management API for multi-window applications and overlays
Implement proper error handling between frontend (JS/TS) and backend (Rust)
Use Tauri plugins for system integration (filesystem, notifications, updater)

Tauri Auto-Updates

Use
```
tauri-plugin-updater
```
for seamless application updates
Implement proper update checking with configurable intervals
Handle update downloads and installations gracefully with user consent
Use code signing for security and trust (especially important on macOS and Windows)
Implement rollback mechanisms for failed updates
Provide clear update progress and status to users
Test update scenarios thoroughly across all target platforms

Electron Applications (Fallback)

Use Electron for desktop applications that need system-level access or complex native integrations
Implement proper IPC (Inter-Process Communication) between main and renderer processes
Use electron-builder for packaging and distribution across Windows, macOS, and Linux
Follow Electron security best practices: disable node integration in renderer, use context isolation
Implement auto-updater functionality for seamless updates
Use native OS features appropriately (notifications, system tray, file associations)

Overlay Applications

Click-through Windows: Use Tauri's window options for transparent, click-through overlays with
```
decorations: false
```
and
```
transparent: true
```
Always on Top: Use Tauri's
```
alwaysOnTop
```
window option for overlay applications
Frameless Windows: Create borderless windows with custom controls using Tauri's window management
Performance Optimization: Leverage Tauri's lightweight architecture to minimize resource usage
Multi-Monitor Support: Handle multiple displays and screen resolution changes using Tauri's monitor APIs
Game Detection: Implement logic to detect when target games are running and position overlays accordingly
System Integration: Use Tauri plugins for deeper OS integration without sacrificing security

macOS Compatibility

File Paths: Use path.join() and avoid hardcoded backslashes; prefer forward slashes or OS-agnostic paths
Case Sensitivity: Assume case-sensitive file systems; maintain consistent casing in imports and file references
Permissions: Handle macOS permission requests for screen recording, accessibility, and file access
Code Signing: Implement proper code signing for macOS distribution and notarization
Native Menus: Use Electron's Menu API to create native macOS menu bars
Keyboard Shortcuts: Use Cmd key equivalents for macOS (Cmd+C instead of Ctrl+C)
File Associations: Register proper file type associations that work across platforms

Security Best Practices

Always sanitize user inputs
Implement proper authentication and authorization
Use HTTPS and secure headers
Follow OWASP security guidelines
Never expose sensitive data in client-side code
Use proper session management and CSRF protection

Error Handling & Resilience

Global Error Handling: Implement centralized error handling using error boundaries in React and global error middleware in Express/Fastify
Typed Errors: Create custom error classes with proper TypeScript types for different error categories (ValidationError, DatabaseError, AuthenticationError, etc.)
Error Logging: Use structured logging (Winston/Pino) with correlation IDs to track errors across services
Graceful Degradation: Design UI components to handle loading, error, and empty states gracefully
User-Friendly Messages: Never expose internal error details to users; provide meaningful, actionable error messages
Retry Logic: Implement exponential backoff for transient failures in API calls and external service integrations
Circuit Breakers: Use circuit breaker patterns for external service dependencies to prevent cascade failures
Input Validation: Validate all inputs at boundaries (API routes, form submissions) using libraries like Zod or Joi
Database Error Handling: Wrap database operations in try-catch blocks and handle specific database errors (constraint violations, connection issues)
API Error Standards: Follow consistent error response formats with proper HTTP status codes, error codes, and messages
Error Monitoring: Integrate with error tracking services (Sentry, Rollbar) for production error monitoring and alerting
Timeout Handling: Set appropriate timeouts for all external requests and handle timeout scenarios gracefully
Null Safety: Use optional chaining, nullish coalescing, and proper null checks to prevent runtime errors
Async Error Handling: Always wrap async operations in try-catch blocks or use proper error handling in Promise chains
Development vs Production: Provide detailed error information in development while sanitizing errors in production environments

Performance Considerations

Implement proper caching strategies
Use code splitting and lazy loading
Optimize database queries and avoid N+1 problems
Implement proper error boundaries in React
Use proper bundling and minification

Development Workflow

Use Git with conventional commit messages
Implement proper CI/CD pipelines
Write unit and integration tests
Use linting and formatting tools (Biome)
Follow semantic versioning

Internal Tools & Automation

Batch Processing: Design tools to handle bulk operations efficiently (image resizing, file processing, data transformation)
Progress Indicators: Implement proper progress tracking and user feedback for long-running operations
File Handling: Use proper streaming for large files, implement drag-and-drop interfaces, and support multiple file formats
Data Transformation: Create reusable utilities for common data parsing and conversion tasks (JSON, CSV, Excel sheets)
CLI Integration: Build command-line interfaces for tools that need to be automated or run in CI/CD pipelines
Configuration Management: Use environment-specific configs and allow easy customization for different use cases
Logging & Monitoring: Implement detailed logging for debugging internal processes and tracking tool usage
Cross-Platform Compatibility: Ensure tools work consistently across Windows and macOS environments
System Integration: Build tools that integrate with OS-specific features (file associations, context menus, system notifications)

Live Data Integration & APIs

Real-time Updates: Use WebSockets or Server-Sent Events for live data feeds from gaming APIs
API Rate Limiting: Implement proper rate limiting and request queuing for external gaming APIs
Data Caching: Cache frequently accessed game data with appropriate TTL based on data volatility
Failover Systems: Design robust fallback mechanisms for when primary data sources are unavailable
Data Validation: Validate incoming API data against expected schemas, especially for live broadcast scenarios
Polling Strategies: Implement intelligent polling intervals based on event urgency and API limitations
Data Normalization: Create consistent data models across different gaming platforms and APIs
Background Jobs: Use job queues for processing non-critical data updates and maintenance tasks

Broadcast & Production Tools

Low Latency: Prioritize minimal delay in data processing for live broadcast scenarios
Data Reliability: Implement redundancy and validation for critical broadcast data
Operator Interfaces: Design simple, clear UIs for non-technical broadcast operators
Emergency Controls: Include manual override capabilities and emergency data reset functions
Asset Management: Build tools for managing and organizing broadcast assets (images, overlays, graphics)
Export Functionality: Provide multiple export formats for integration with broadcast software
Schedule Integration: Handle time-zone conversions and match scheduling complexities

Stage Effects & Lighting Integration

OSC Communication: Use Open Sound Control for real-time communication with lighting consoles, stage effects, and visual systems
Event-Driven Triggers: Implement responsive systems that trigger effects based on game events (kills, objectives, draft phases)
Multiple Target Support: Design systems to communicate with various broadcast tools (Notch, Resolume, lighting consoles) simultaneously
State Management: Track game state changes to prevent duplicate triggers and ensure effects sync with actual events
Timestamp Validation: Implement safeguards against rapid-fire events using timestamp comparison and debouncing
Configuration-Driven Effects: Make effect mappings, OSC addresses, and timing parameters easily configurable via JSON
Failover Communication: Handle network failures gracefully and provide manual trigger capabilities for critical moments
Real-time Monitoring: Implement logging and status monitoring for all outgoing OSC/HTTP triggers
Team State Awareness: Track team positioning, draft state, and match progression to trigger contextually appropriate effects

Things to Avoid

Avoid JavaScript/TypeScript classes in favor of functional approaches - use object literals, factory functions, or modules instead unless the project already has established class usage
Avoid direct DOM manipulation in React components; always prefer state-driven rendering or using Refs appropriately.
Avoid introducing new dependencies without strong justification and checking for existing alternatives within the project or preferred libraries.
Avoid overly complex abstractions or design patterns if simpler solutions suffice and maintain readability.
Avoid using deprecated browser APIs or library features unless there's a critical, unresolvable need.
Avoid committing commented-out code blocks; remove them or use version control history.
Avoid blocking the main thread for CPU-intensive operations; use Web Workers or background processing
Avoid hardcoding API endpoints, timeouts, or batch sizes; make them configurable
Avoid using anything other than bun as the package manager for new projects; use it consistently across the codebase

Response Guidelines

When providing code suggestions:

Explain the approach - Briefly describe what the code does and why
Provide complete examples - Include all necessary imports and dependencies
Include error handling - Always consider edge cases and error scenarios
Maintain consistency - Follow existing codebase patterns and conventions
Suggest improvements - Offer alternative approaches or optimizations when relevant
Consider the context - Take into account the existing project structure and dependencies

Code Example Format

When showing code:

Include relevant imports
Add TypeScript types where applicable
Include basic error handling
Add brief comments for complex logic
Show usage examples when helpful

Remember to always consider the existing codebase patterns and maintain consistency with the established architecture and conventions.