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
2025-12-23 21:57:45 -06:00 · 2025-09-17 15:43:32 -03:00
parent 805f40c841
commit 7088ad05d2
19 changed files with 6939 additions and 63 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,77 +2,163 @@

 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

-## Development Commands
+## Project Overview

-### Core Commands
- **Run development server**: `npm run dev:server` - Starts the server with hot reload using tsx watch
- **Build project**: `npm run build` - Runs TypeScript check and builds with tsup
- **Start production**: `npm run start:prod` - Runs the compiled application from dist/
- **Lint code**: `npm run lint` - Runs ESLint with auto-fix on TypeScript files
- **Check lint**: `npm run lint:check` - Runs ESLint without auto-fix
+Evolution API is a REST API for WhatsApp communication that supports both Baileys (WhatsApp Web) and official WhatsApp Business API. It's built with TypeScript/Node.js and provides extensive integrations with various platforms.

-### Database Commands
-The project uses Prisma with support for multiple database providers (PostgreSQL, MySQL, psql_bouncer). Commands automatically use the DATABASE_PROVIDER from .env:
+## Common Development Commands

- **Generate Prisma client**: `npm run db:generate`
- **Deploy migrations**: `npm run db:deploy` (Unix/Mac) or `npm run db:deploy:win` (Windows)
- **Open Prisma Studio**: `npm run db:studio`
- **Create new migration**: `npm run db:migrate:dev` (Unix/Mac) or `npm run db:migrate:dev:win` (Windows)
+### Build and Run
+```bash
+# Development
+npm run dev:server    # Run in development with hot reload (tsx watch)
+
+# Production
+npm run build        # TypeScript check + tsup build
+npm run start:prod   # Run production build
+
+# Direct execution
+npm start           # Run with tsx
+```
+
+### Code Quality
+```bash
+npm run lint        # ESLint with auto-fix
+npm run lint:check  # ESLint check only
+npm run commit      # Interactive commit with commitizen
+```
+
+### Database Management
+```bash
+# Generate Prisma client (automatically uses DATABASE_PROVIDER env)
+npm run db:generate
+
+# Deploy migrations
+npm run db:deploy      # Unix/Mac
+npm run db:deploy:win  # Windows
+
+# Open Prisma Studio
+npm run db:studio
+
+# Development migrations
+npm run db:migrate:dev      # Unix/Mac
+npm run db:migrate:dev:win  # Windows
+```
+
+### Testing
+```bash
+npm test    # Run tests with watch mode
+```

 ## Architecture Overview

-### Project Structure
-Evolution API is a WhatsApp integration platform built with TypeScript and Express, supporting both Baileys (WhatsApp Web) and WhatsApp Cloud API connections.
+### Core Structure
+- **Multi-provider database support**: PostgreSQL and MySQL via Prisma ORM with provider-specific schemas
+- **Connection management**: Each WhatsApp instance maintains its own connection state and session
+- **Event-driven architecture**: Uses EventEmitter2 for internal events and supports multiple external event systems

-### Core Components
+### Directory Layout
+```
+src/
+├── api/
+│   ├── controllers/     # HTTP route handlers
+│   ├── services/        # Business logic
+│   ├── repository/      # Data access layer (Prisma)
+│   ├── dto/            # Data validation schemas
+│   ├── guards/         # Authentication/authorization
+│   ├── integrations/   # External service integrations
+│   └── routes/         # Express route definitions
+├── config/             # Environment and app configuration
+├── cache/             # Redis and local cache implementations
+├── exceptions/        # Custom exception classes
+├── utils/            # Shared utilities
+└── validate/         # Validation schemas
+```

-**API Layer** (`src/api/`)
- **Controllers**: Handle HTTP requests for different resources (instance, chat, group, sendMessage, etc.)
- **Services**: Business logic layer containing auth, cache, channel, monitor, proxy services
- **Routes**: RESTful API endpoints with authentication guards
- **DTOs**: Data transfer objects for request/response validation using class-validator
- **Repository**: Database access layer using Prisma ORM
+### Key Services Integration Points

-**Integrations** (`src/api/integrations/`)
- **Chatbot**: Supports multiple chatbot platforms (Typebot, Chatwoot, Dify, OpenAI, Flowise, N8N)
- **Event**: WebSocket, RabbitMQ, Amazon SQS event systems
- **Storage**: S3/Minio file storage integration
- **Channel**: Multi-channel messaging support
+**WhatsApp Service** (`src/api/integrations/channel/whatsapp/`):
+- Manages Baileys connections and Meta Business API
+- Handles message sending, receiving, and status updates
+- Connection lifecycle management per instance

-**Configuration** (`src/config/`)
- Environment configuration management
- Database provider switching (PostgreSQL/MySQL/PgBouncer)
- Multi-tenant support via DATABASE_CONNECTION_CLIENT_NAME
+**Integration Services** (`src/api/integrations/`):
+- Chatwoot: Customer service platform integration
+- Typebot: Conversational bot builder
+- OpenAI: AI capabilities including audio transcription
+- Dify: AI agent platform
+- RabbitMQ/SQS: Message queue integrations
+- S3/Minio: Media storage

-### Key Design Patterns
-
-1. **Multi-Provider Database**: Uses `runWithProvider.js` to dynamically select database provider and migrations
-2. **Module System**: Path aliases configured in tsconfig.json (@api, @cache, @config, @utils, @validate)
-3. **Event-Driven**: EventEmitter2 for internal events, supports multiple external event systems
-4. **Instance Management**: Each WhatsApp connection is managed as an instance with memory lifecycle (DEL_INSTANCE config)
-
-### Database Schema
- Supports multiple providers with provider-specific schemas in `prisma/`
- Separate migration folders for each provider (postgresql-migrations, mysql-migrations)
- psql_bouncer uses PostgreSQL migrations but with connection pooling
+### Database Schema Management
+- Separate schema files: `postgresql-schema.prisma` and `mysql-schema.prisma`
+- Environment variable `DATABASE_PROVIDER` determines active database
+- Migration folders are provider-specific and auto-selected during deployment

 ### Authentication & Security
- JWT-based authentication
- API key support
- Instance-specific authentication
- Configurable CORS settings
+- API key-based authentication via `apikey` header
+- Instance-specific authentication for WhatsApp connections
+- Guards system for route protection
+- Input validation using `class-validator`

-### Messaging Features
- WhatsApp Web (Baileys library) and WhatsApp Cloud API support
- Message queue support (RabbitMQ, SQS)
- Real-time updates via WebSocket
- Media file handling with S3/Minio storage
- Multiple chatbot integrations with trigger management
+## Important Implementation Details

-### Environment Variables
-Critical configuration in `.env`:
- SERVER_TYPE, SERVER_PORT, SERVER_URL
- DATABASE_PROVIDER and DATABASE_CONNECTION_URI
- Log levels and Baileys-specific logging
- Instance lifecycle management (DEL_INSTANCE)
- Feature toggles for data persistence (DATABASE_SAVE_*)
+### WhatsApp Instance Management
+- Each WhatsApp connection is an "instance" with unique name
+- Instance data stored in database with connection state
+- Session persistence in database or file system (configurable)
+- Automatic reconnection handling with exponential backoff
+
+### Message Queue Architecture
+- Supports RabbitMQ, Amazon SQS, and WebSocket for events
+- Event types: message.received, message.sent, connection.update, etc.
+- Configurable per instance which events to send
+
+### Media Handling
+- Local storage or S3/Minio for media files
+- Automatic media download from WhatsApp
+- Media URL generation for external access
+- Support for audio transcription via OpenAI
+
+### Multi-tenancy Support
+- Instance isolation at database level
+- Separate webhook configurations per instance
+- Independent integration settings per instance
+
+## Environment Configuration
+
+Key environment variables are defined in `.env.example`. The system uses a strongly-typed configuration system via `src/config/env.config.ts`.
+
+Critical configurations:
+- `DATABASE_PROVIDER`: postgresql or mysql
+- `DATABASE_CONNECTION_URI`: Database connection string
+- `AUTHENTICATION_API_KEY`: Global API authentication
+- `REDIS_ENABLED`: Enable Redis cache
+- `RABBITMQ_ENABLED`/`SQS_ENABLED`: Message queue options
+
+## Development Guidelines from Cursor Instructions
+
+The project includes specific development instructions in `.cursor/instructions`:
+- Always respond in Portuguese Brazilian
+- Follow established architecture patterns
+- Robust error handling with retry logic
+- Multi-database compatibility requirements
+- Security validations and rate limiting
+- Performance optimizations with caching
+- Minimum 70% test coverage target
+
+## Testing Approach
+
+Tests are located alongside source files or in dedicated test directories. The project uses:
+- Unit tests for services
+- Integration tests for critical APIs
+- Mock external dependencies
+- Test command runs with watch mode for development
+
+## Deployment Considerations
+
+- Docker support with `Dockerfile` and `docker-compose.yaml`
+- Graceful shutdown handling for connections
+- Health check endpoints for monitoring
+- Sentry integration for error tracking
+- Telemetry for usage analytics (non-sensitive data only)