Skip to content

Commit 7088ad0

Browse files
DavidsonGomesDavidsonGomes
committed
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
1 parent 805f40c commit 7088ad0

19 files changed

+6940
-64
lines changed

‎.cursor/rules/README.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# Evolution API Cursor Rules
2+
3+
Este diretório contém as regras e configurações do Cursor IDE para o projeto Evolution API.
4+
5+
## Estrutura dos Arquivos
6+
7+
### Arquivos Principais (alwaysApply: true)
8+
- **`core-development.mdc`** - Princípios fundamentais de desenvolvimento
9+
- **`project-context.mdc`** - Contexto específico do projeto Evolution API
10+
- **`cursor.json`** - Configurações do Cursor IDE
11+
12+
### Regras Especializadas (alwaysApply: false)
13+
Estas regras são ativadas automaticamente quando você trabalha nos arquivos correspondentes:
14+
15+
#### Camadas da Aplicação
16+
- **`specialized-rules/service-rules.mdc`** - Padrões para services (`src/api/services/`)
17+
- **`specialized-rules/controller-rules.mdc`** - Padrões para controllers (`src/api/controllers/`)
18+
- **`specialized-rules/dto-rules.mdc`** - Padrões para DTOs (`src/api/dto/`)
19+
- **`specialized-rules/guard-rules.mdc`** - Padrões para guards (`src/api/guards/`)
20+
- **`specialized-rules/route-rules.mdc`** - Padrões para routers (`src/api/routes/`)
21+
22+
#### Tipos e Validação
23+
- **`specialized-rules/type-rules.mdc`** - Definições TypeScript (`src/api/types/`)
24+
- **`specialized-rules/validate-rules.mdc`** - Schemas de validação (`src/validate/`)
25+
26+
#### Utilitários
27+
- **`specialized-rules/util-rules.mdc`** - Funções utilitárias (`src/utils/`)
28+
29+
#### Integrações
30+
- **`specialized-rules/integration-channel-rules.mdc`** - Integrações de canal (`src/api/integrations/channel/`)
31+
- **`specialized-rules/integration-chatbot-rules.mdc`** - Integrações de chatbot (`src/api/integrations/chatbot/`)
32+
- **`specialized-rules/integration-storage-rules.mdc`** - Integrações de storage (`src/api/integrations/storage/`)
33+
- **`specialized-rules/integration-event-rules.mdc`** - Integrações de eventos (`src/api/integrations/event/`)
34+
35+
## Como Usar
36+
37+
### Referências Cruzadas
38+
Os arquivos principais fazem referência aos especializados usando a sintaxe `@specialized-rules/nome-do-arquivo.mdc`. Quando você trabalha em um arquivo específico, o Cursor automaticamente carrega as regras relevantes.
39+
40+
### Exemplo de Uso
41+
Quando você edita um arquivo em `src/api/services/`, o Cursor automaticamente:
42+
1. Carrega `core-development.mdc` (sempre ativo)
43+
2. Carrega `project-context.mdc` (sempre ativo)
44+
3. Carrega `specialized-rules/service-rules.mdc` (ativado pelo glob pattern)
45+
46+
### Padrões de Código
47+
Cada arquivo de regras contém:
48+
- **Estruturas padrão** - Como organizar o código
49+
- **Padrões de nomenclatura** - Convenções de nomes
50+
- **Exemplos práticos** - Código de exemplo
51+
- **Anti-padrões** - O que evitar
52+
- **Testes** - Como testar o código
53+
54+
## Configuração do Cursor
55+
56+
O arquivo `cursor.json` contém:
57+
- Configurações de formatação
58+
- Padrões de código específicos do Evolution API
59+
- Diretórios principais do projeto
60+
- Integrações e tecnologias utilizadas
61+
62+
## Manutenção
63+
64+
Para manter as regras atualizadas:
65+
1. Analise novos padrões no código
66+
2. Atualize as regras especializadas correspondentes
67+
3. Mantenha os exemplos sincronizados com o código real
68+
4. Documente mudanças significativas
69+
70+
## Tecnologias Cobertas
71+
72+
- **Backend**: Node.js 20+ + TypeScript 5+ + Express.js
73+
- **Database**: Prisma ORM (PostgreSQL/MySQL)
74+
- **Cache**: Redis + Node-cache
75+
- **Queue**: RabbitMQ + Amazon SQS
76+
- **Real-time**: Socket.io
77+
- **Storage**: AWS S3 + Minio
78+
- **Validation**: class-validator + Joi
79+
- **Logging**: Pino
80+
- **WhatsApp**: Baileys + Meta Business API
81+
- **Integrations**: Chatwoot, Typebot, OpenAI, Dify
82+
83+
## Estrutura do Projeto
84+
85+
```
86+
src/
87+
├── api/
88+
│ ├── controllers/ # Controllers (HTTP handlers)
89+
│ ├── services/ # Business logic
90+
│ ├── dto/ # Data Transfer Objects
91+
│ ├── guards/ # Authentication/Authorization
92+
│ ├── routes/ # Express routers
93+
│ ├── types/ # TypeScript definitions
94+
│ └── integrations/ # External integrations
95+
│ ├── channel/ # WhatsApp channels (Baileys, Business API)
96+
│ ├── chatbot/ # Chatbot integrations
97+
│ ├── event/ # Event integrations
98+
│ └── storage/ # Storage integrations
99+
├── cache/ # Cache implementations
100+
├── config/ # Configuration files
101+
├── utils/ # Utility functions
102+
├── validate/ # Validation schemas
103+
└── exceptions/ # Custom exceptions
104+
```
105+
106+
Este sistema de regras garante consistência no código e facilita o desenvolvimento seguindo os padrões estabelecidos do Evolution API.

‎.cursor/rules/core-development.mdc‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
---
2+
description: Core development principles and standards for Evolution API development
3+
globs:
4+
alwaysApply: true
5+
---
6+
7+
# Evolution API Development Standards
8+
9+
## Cross-References
10+
- **Project Context**: @project-context.mdc for Evolution API-specific patterns
11+
- **Specialized Rules**:
12+
- @specialized-rules/service-rules.mdc for service layer patterns
13+
- @specialized-rules/controller-rules.mdc for controller patterns
14+
- @specialized-rules/dto-rules.mdc for DTO validation patterns
15+
- @specialized-rules/guard-rules.mdc for authentication/authorization
16+
- @specialized-rules/route-rules.mdc for router patterns
17+
- @specialized-rules/type-rules.mdc for TypeScript definitions
18+
- @specialized-rules/util-rules.mdc for utility functions
19+
- @specialized-rules/validate-rules.mdc for validation schemas
20+
- @specialized-rules/integration-channel-rules.mdc for channel integrations
21+
- @specialized-rules/integration-chatbot-rules.mdc for chatbot integrations
22+
- @specialized-rules/integration-storage-rules.mdc for storage integrations
23+
- @specialized-rules/integration-event-rules.mdc for event integrations
24+
- **TypeScript/Node.js**: Node.js 20+ + TypeScript 5+ best practices
25+
- **Express/Prisma**: Express.js + Prisma ORM patterns
26+
- **WhatsApp Integrations**: Baileys + Meta Business API patterns
27+
28+
## Senior Engineer Context - Evolution API Platform
29+
- You are a senior software engineer working on a WhatsApp API platform
30+
- Focus on Node.js + TypeScript + Express.js full-stack development
31+
- Specialized in real-time messaging, WhatsApp integrations, and event-driven architecture
32+
- Apply scalable patterns for multi-tenant API platform
33+
- Consider WhatsApp integration workflow implications and performance at scale
34+
35+
## Fundamental Principles
36+
37+
### Code Quality Standards
38+
- **Simplicity First**: Always prefer simple solutions over complex ones
39+
- **DRY Principle**: Avoid code duplication - check for existing similar functionality before implementing
40+
- **Single Responsibility**: Each function/class should have one clear purpose
41+
- **Readable Code**: Write code that tells a story - clear naming and structure
42+
43+
### Problem Resolution Approach
44+
- **Follow Existing Patterns**: Use established Service patterns, DTOs, and Integration patterns
45+
- **Event-Driven First**: Leverage EventEmitter2 for event publishing when adding new features
46+
- **Integration Pattern**: Follow existing WhatsApp integration patterns for new channels
47+
- **Conservative Changes**: Prefer extending existing services over creating new architecture
48+
- **Clean Migration**: Remove deprecated patterns when introducing new ones
49+
- **Incremental Changes**: Break large changes into smaller, testable increments with proper migrations
50+
51+
### File and Function Organization - Node.js/TypeScript Structure
52+
- **Services**: Keep services focused and under 200 lines
53+
- **Controllers**: Keep controllers thin - only routing and validation
54+
- **DTOs**: Use class-validator for all input validation
55+
- **Integrations**: Follow `src/api/integrations/` structure for new integrations
56+
- **Utils**: Extract common functionality into well-named utilities
57+
- **Types**: Define clear TypeScript interfaces and types
58+
59+
### Code Analysis and Reflection
60+
- After writing code, deeply reflect on scalability and maintainability
61+
- Provide 1-2 paragraph analysis of code changes
62+
- Suggest improvements or next steps based on reflection
63+
- Consider performance, security, and maintenance implications
64+
65+
## Development Standards
66+
67+
### TypeScript Standards
68+
- **Strict Mode**: Always use TypeScript strict mode
69+
- **No Any**: Avoid `any` type - use proper typing
70+
- **Interfaces**: Define clear contracts with interfaces
71+
- **Enums**: Use enums for constants and status values
72+
- **Generics**: Use generics for reusable components
73+
74+
### Error Handling Standards
75+
- **HTTP Exceptions**: Use appropriate HTTP status codes
76+
- **Logging**: Structured logging with context
77+
- **Retry Logic**: Implement retry for external services
78+
- **Graceful Degradation**: Handle service failures gracefully
79+
80+
### Security Standards
81+
- **Input Validation**: Validate all inputs with class-validator
82+
- **Authentication**: Use API keys and JWT tokens
83+
- **Rate Limiting**: Implement rate limiting for APIs
84+
- **Data Sanitization**: Sanitize sensitive data in logs
85+
86+
### Performance Standards
87+
- **Caching**: Use Redis for frequently accessed data
88+
- **Database**: Optimize Prisma queries with proper indexing
89+
- **Memory**: Monitor memory usage and implement cleanup
90+
- **Async**: Use async/await properly with error handling
91+
92+
## Communication Standards
93+
94+
### Language Requirements
95+
- **User Communication**: Always respond in Portuguese (PT-BR)
96+
- **Code Comments**: English for technical documentation
97+
- **API Documentation**: English for consistency
98+
- **Error Messages**: Portuguese for user-facing errors
99+
100+
### Documentation Standards
101+
- **Code Comments**: Document complex business logic
102+
- **API Documentation**: Document all public endpoints
103+
- **README**: Keep project documentation updated
104+
- **Changelog**: Document breaking changes
105+
106+
## Quality Assurance
107+
108+
### Testing Standards
109+
- **Unit Tests**: Test business logic in services
110+
- **Integration Tests**: Test API endpoints
111+
- **Mocks**: Mock external dependencies
112+
- **Coverage**: Aim for 70%+ test coverage
113+
114+
### Code Review Standards
115+
- **Peer Review**: All code must be reviewed
116+
- **Automated Checks**: ESLint, Prettier, TypeScript
117+
- **Security Review**: Check for security vulnerabilities
118+
- **Performance Review**: Check for performance issues
119+
120+
## Evolution API Specific Patterns
121+
122+
### WhatsApp Integration Patterns
123+
- **Connection Management**: One connection per instance
124+
- **Event Handling**: Proper event listeners for Baileys
125+
- **Message Processing**: Queue-based message processing
126+
- **Error Recovery**: Automatic reconnection logic
127+
128+
### Multi-Database Support
129+
- **Schema Compatibility**: Support PostgreSQL and MySQL
130+
- **Migration Sync**: Keep migrations synchronized
131+
- **Type Safety**: Use Prisma generated types
132+
- **Connection Pooling**: Proper database connection management
133+
134+
### Cache Strategy
135+
- **Redis Primary**: Use Redis for distributed caching
136+
- **Local Fallback**: Node-cache for local fallback
137+
- **TTL Strategy**: Appropriate TTL for different data types
138+
- **Cache Invalidation**: Proper cache invalidation patterns
139+
140+
### Event System
141+
- **EventEmitter2**: Use for internal events
142+
- **WebSocket**: Socket.io for real-time updates
143+
- **Queue Systems**: RabbitMQ/SQS for async processing
144+
- **Webhook Processing**: Proper webhook validation and processing

0 commit comments

Comments
 (0)