mirror of
https://github.com/EvolutionAPI/evolution-api.git
synced 2025-12-18 19:32:21 -06:00
feat: add project guidelines and configuration files for development standards
- 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
This commit is contained in:
Davidson Gomes
174
.cursor/rules/project-context.mdc
Normal file
174
.cursor/rules/project-context.mdc
Normal file
@@ -0,0 +1,174 @@
|
||||
---
|
||||
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
|
||||
Reference in New Issue
Block a user