mirror of
https://github.com/EvolutionAPI/evolution-api.git
synced 2025-12-09 09:59:40 -06:00
7088ad05d2
- Introduce AGENTS.md for repository guidelines and project structure - Add core development principles in .cursor/rules/core-development.mdc - Establish project-specific context in .cursor/rules/project-context.mdc - Implement Cursor IDE configuration in .cursor/rules/cursor.json - Create specialized rules for controllers, services, DTOs, guards, routes, and integrations - Update .gitignore to exclude unnecessary files - Enhance CLAUDE.md with project overview and common development commands
174 lines
7.4 KiB
Plaintext
174 lines
7.4 KiB
Plaintext
---
|
|
description: Evolution API project-specific context and constraints
|
|
globs:
|
|
alwaysApply: true
|
|
---
|
|
|
|
# Evolution API Project Context
|
|
|
|
## Cross-References
|
|
- **Core Development**: @core-development.mdc for fundamental development principles
|
|
- **Specialized Rules**: Reference specific specialized rules when working on:
|
|
- Services: @specialized-rules/service-rules.mdc
|
|
- Controllers: @specialized-rules/controller-rules.mdc
|
|
- DTOs: @specialized-rules/dto-rules.mdc
|
|
- Guards: @specialized-rules/guard-rules.mdc
|
|
- Routes: @specialized-rules/route-rules.mdc
|
|
- Types: @specialized-rules/type-rules.mdc
|
|
- Utils: @specialized-rules/util-rules.mdc
|
|
- Validation: @specialized-rules/validate-rules.mdc
|
|
- Channel Integrations: @specialized-rules/integration-channel-rules.mdc
|
|
- Chatbot Integrations: @specialized-rules/integration-chatbot-rules.mdc
|
|
- Storage Integrations: @specialized-rules/integration-storage-rules.mdc
|
|
- Event Integrations: @specialized-rules/integration-event-rules.mdc
|
|
- **TypeScript/Node.js**: Node.js 20+ + TypeScript 5+ backend standards
|
|
- **Express/Prisma**: Express.js + Prisma ORM patterns
|
|
- **WhatsApp Integrations**: Baileys, Meta Business API, and other messaging platforms
|
|
|
|
## Technology Stack
|
|
- **Backend**: Node.js 20+ + TypeScript 5+ + Express.js
|
|
- **Database**: Prisma ORM (PostgreSQL/MySQL support)
|
|
- **Cache**: Redis + Node-cache for local fallback
|
|
- **Queue**: RabbitMQ + Amazon SQS for message processing
|
|
- **Real-time**: Socket.io for WebSocket connections
|
|
- **Storage**: AWS S3 + Minio for file storage
|
|
- **Validation**: class-validator for input validation
|
|
- **Logging**: Pino for structured logging
|
|
- **Architecture**: Multi-tenant API with WhatsApp integrations
|
|
|
|
## Project-Specific Patterns
|
|
|
|
### WhatsApp Integration Architecture
|
|
- **MANDATORY**: All WhatsApp integrations must follow established patterns
|
|
- **BAILEYS**: Use `whatsapp.baileys.service.ts` patterns for WhatsApp Web
|
|
- **META BUSINESS**: Use `whatsapp.business.service.ts` for official API
|
|
- **CONNECTION MANAGEMENT**: One connection per instance with proper lifecycle
|
|
- **EVENT HANDLING**: Proper event listeners and error handling
|
|
|
|
### Multi-Database Architecture
|
|
- **CRITICAL**: Support both PostgreSQL and MySQL
|
|
- **SCHEMAS**: Use appropriate schema files (postgresql-schema.prisma / mysql-schema.prisma)
|
|
- **MIGRATIONS**: Keep migrations synchronized between databases
|
|
- **TYPES**: Use database-specific types (@db.JsonB vs @db.Json)
|
|
- **COMPATIBILITY**: Ensure feature parity between databases
|
|
|
|
### API Integration Workflow
|
|
- **CORE FEATURE**: REST API for WhatsApp communication
|
|
- **COMPLEXITY**: High - involves webhook processing, message routing, and instance management
|
|
- **COMPONENTS**: Instance management, message handling, media processing
|
|
- **INTEGRATIONS**: Baileys, Meta Business API, Chatwoot, Typebot, OpenAI, Dify
|
|
|
|
### Multi-Tenant Instance Architecture
|
|
- **CRITICAL**: All operations must be scoped by instance
|
|
- **ISOLATION**: Complete data isolation between instances
|
|
- **SECURITY**: Validate instance ownership before operations
|
|
- **SCALING**: Support thousands of concurrent instances
|
|
- **AUTHENTICATION**: API key-based authentication per instance
|
|
|
|
## Documentation Requirements
|
|
|
|
### Implementation Documentation
|
|
- **MANDATORY**: Document complex integration patterns
|
|
- **LOCATION**: Use inline comments for business logic
|
|
- **API DOCS**: Document all public endpoints
|
|
- **WEBHOOK DOCS**: Document webhook payloads and signatures
|
|
|
|
### Change Documentation
|
|
- **CHANGELOG**: Document breaking changes
|
|
- **MIGRATION GUIDES**: Document database migrations
|
|
- **INTEGRATION GUIDES**: Document new integration patterns
|
|
|
|
## Environment and Security
|
|
|
|
### Environment Variables
|
|
- **CRITICAL**: Never hardcode sensitive values
|
|
- **VALIDATION**: Validate required environment variables on startup
|
|
- **SECURITY**: Use secure defaults and proper encryption
|
|
- **DOCUMENTATION**: Document all environment variables
|
|
|
|
### File Organization - Node.js/TypeScript Structure
|
|
- **CONTROLLERS**: Organized by feature (`api/controllers/`)
|
|
- **SERVICES**: Business logic in service classes (`api/services/`)
|
|
- **INTEGRATIONS**: External integrations (`api/integrations/`)
|
|
- **DTOS**: Data transfer objects (`api/dto/`)
|
|
- **TYPES**: TypeScript types (`api/types/`)
|
|
- **UTILS**: Utility functions (`utils/`)
|
|
|
|
## Integration Points
|
|
|
|
### WhatsApp Providers
|
|
- **BAILEYS**: WhatsApp Web integration with QR code
|
|
- **META BUSINESS**: Official WhatsApp Business API
|
|
- **CLOUD API**: WhatsApp Cloud API integration
|
|
- **WEBHOOK PROCESSING**: Proper webhook validation and processing
|
|
|
|
### External Integrations
|
|
- **CHATWOOT**: Customer support platform integration
|
|
- **TYPEBOT**: Chatbot flow integration
|
|
- **OPENAI**: AI-powered chat integration
|
|
- **DIFY**: AI workflow integration
|
|
- **STORAGE**: S3/Minio for media file storage
|
|
|
|
### Event-Driven Communication
|
|
- **EVENTEMITTER2**: Internal event system
|
|
- **SOCKET.IO**: Real-time WebSocket communication
|
|
- **RABBITMQ**: Message queue for async processing
|
|
- **SQS**: Amazon SQS for cloud-based queuing
|
|
- **WEBHOOKS**: Outbound webhook system
|
|
|
|
## Development Constraints
|
|
|
|
### Language Requirements
|
|
- **USER COMMUNICATION**: Always respond in Portuguese (PT-BR)
|
|
- **CODE/COMMENTS**: English for code and technical documentation
|
|
- **API RESPONSES**: English for consistency
|
|
- **ERROR MESSAGES**: Portuguese for user-facing errors
|
|
|
|
### Performance Constraints
|
|
- **MEMORY**: Efficient memory usage for multiple instances
|
|
- **DATABASE**: Optimized queries with proper indexing
|
|
- **CACHE**: Strategic caching for frequently accessed data
|
|
- **CONNECTIONS**: Proper connection pooling and management
|
|
|
|
### Security Constraints
|
|
- **AUTHENTICATION**: API key validation for all endpoints
|
|
- **AUTHORIZATION**: Instance-based access control
|
|
- **INPUT VALIDATION**: Validate all inputs with class-validator
|
|
- **RATE LIMITING**: Prevent abuse with rate limiting
|
|
- **WEBHOOK SECURITY**: Validate webhook signatures
|
|
|
|
## Quality Standards
|
|
- **TYPE SAFETY**: Full TypeScript coverage with strict mode
|
|
- **ERROR HANDLING**: Comprehensive error scenarios with proper logging
|
|
- **TESTING**: Unit and integration tests for critical paths
|
|
- **MONITORING**: Proper logging and error tracking
|
|
- **DOCUMENTATION**: Clear API documentation and code comments
|
|
- **PERFORMANCE**: Optimized for high-throughput message processing
|
|
- **SECURITY**: Secure by default with proper validation
|
|
- **SCALABILITY**: Design for horizontal scaling
|
|
|
|
## Evolution API Specific Development Patterns
|
|
|
|
### Instance Management
|
|
- **LIFECYCLE**: Proper instance creation, connection, and cleanup
|
|
- **STATE MANAGEMENT**: Track connection status and health
|
|
- **RECOVERY**: Automatic reconnection and error recovery
|
|
- **MONITORING**: Health checks and status reporting
|
|
|
|
### Message Processing
|
|
- **QUEUE-BASED**: Use queues for message processing
|
|
- **RETRY LOGIC**: Implement exponential backoff for failures
|
|
- **MEDIA HANDLING**: Proper media upload and processing
|
|
- **WEBHOOK DELIVERY**: Reliable webhook delivery with retries
|
|
|
|
### Integration Patterns
|
|
- **SERVICE LAYER**: Business logic in service classes
|
|
- **DTO VALIDATION**: Input validation with class-validator
|
|
- **ERROR HANDLING**: Consistent error responses
|
|
- **LOGGING**: Structured logging with correlation IDs
|
|
|
|
### Database Patterns
|
|
- **PRISMA**: Use Prisma ORM for all database operations
|
|
- **TRANSACTIONS**: Use transactions for multi-step operations
|
|
- **MIGRATIONS**: Proper migration management
|
|
- **INDEXING**: Optimize queries with appropriate indexes |