docs(agents.md and claude.md): update and expand AI Agent guidelines in AGENTS.md and CLAUDE.md

Revise AGENTS.md to provide comprehensive guidelines for AI agents working with the Evolution API. Enhance CLAUDE.md with detailed project overview, common development commands, and integration points. Include architecture patterns, coding standards, and testing strategies for better clarity and consistency.
2025-12-25 22:57:44 -06:00 · 2025-09-17 15:54:39 -03:00
parent a721beda3c
commit 81a991a62e
2 changed files with 446 additions and 73 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,10 +1,15 @@
 # CLAUDE.md

-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+This file provides comprehensive guidance to Claude AI when working with the Evolution API codebase.

 ## Project Overview

-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.
+**Evolution API** is a powerful, production-ready REST API for WhatsApp communication that supports multiple WhatsApp providers:
+- **Baileys** (WhatsApp Web) - Open-source WhatsApp Web client
+- **Meta Business API** - Official WhatsApp Business API
+- **Evolution API** - Custom WhatsApp integration
+
+Built with **Node.js 20+**, **TypeScript 5+**, and **Express.js**, it provides extensive integrations with chatbots, CRM systems, and messaging platforms in a **multi-tenant architecture**.

 ## Common Development Commands

@@ -30,13 +35,20 @@ npm run commit      # Interactive commit with commitizen

 ### Database Management
 ```bash
+# Set database provider first
+export DATABASE_PROVIDER=postgresql  # or mysql
+
 # Generate Prisma client (automatically uses DATABASE_PROVIDER env)
 npm run db:generate

-# Deploy migrations
+# Deploy migrations (production)
 npm run db:deploy      # Unix/Mac
 npm run db:deploy:win  # Windows

+# Development migrations (with sync to provider folder)
+npm run db:migrate:dev      # Unix/Mac
+npm run db:migrate:dev:win  # Windows
+
 # Open Prisma Studio
 npm run db:studio

@@ -53,42 +65,64 @@ npm test    # Run tests with watch mode
 ## Architecture Overview

 ### 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
+- **Multi-tenant SaaS**: Complete instance isolation with per-tenant authentication
+- **Multi-provider database**: PostgreSQL and MySQL via Prisma ORM with provider-specific schemas and migrations
+- **WhatsApp integrations**: Baileys, Meta Business API, and Evolution API with unified interface
+- **Event-driven architecture**: EventEmitter2 for internal events + WebSocket, RabbitMQ, SQS, NATS, Pusher for external events
+- **Microservices pattern**: Modular integrations for chatbots, storage, and external services

 ### Directory Layout
 ```
 src/
 ├── api/
-│   ├── controllers/     # HTTP route handlers
-│   ├── services/        # Business logic
+│   ├── controllers/     # HTTP route handlers (thin layer)
+│   ├── services/        # Business logic (core functionality)
 │   ├── repository/      # Data access layer (Prisma)
-│   ├── dto/            # Data validation schemas
-│   ├── guards/         # Authentication/authorization
+│   ├── dto/            # Data Transfer Objects (simple classes)
+│   ├── guards/         # Authentication/authorization middleware
 │   ├── integrations/   # External service integrations
-│   └── routes/         # Express route definitions
+│   │   ├── channel/    # WhatsApp providers (Baileys, Business API, Evolution)
+│   │   ├── chatbot/    # AI/Bot integrations (OpenAI, Dify, Typebot, Chatwoot)
+│   │   ├── event/      # Event systems (WebSocket, RabbitMQ, SQS, NATS, Pusher)
+│   │   └── storage/    # File storage (S3, MinIO)
+│   ├── routes/         # Express route definitions (RouterBroker pattern)
+│   └── types/          # TypeScript type definitions
 ├── config/             # Environment and app configuration
 ├── cache/             # Redis and local cache implementations
-├── exceptions/        # Custom exception classes
-├── utils/            # Shared utilities
-└── validate/         # Validation schemas
+├── exceptions/        # Custom HTTP exception classes
+├── utils/            # Shared utilities and helpers
+└── validate/         # JSONSchema7 validation schemas
 ```

-### Key Services Integration Points
+### Key Integration Points

-**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
+**Channel Integrations** (`src/api/integrations/channel/`):
+- **Baileys**: WhatsApp Web client with QR code authentication
+- **Business API**: Official Meta WhatsApp Business API
+- **Evolution API**: Custom WhatsApp integration
+- Connection lifecycle management per instance with automatic reconnection

-**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
+**Chatbot Integrations** (`src/api/integrations/chatbot/`):
+- **EvolutionBot**: Native chatbot with trigger system
+- **Chatwoot**: Customer service platform integration
+- **Typebot**: Visual chatbot flow builder
+- **OpenAI**: AI capabilities including GPT and Whisper (audio transcription)
+- **Dify**: AI agent workflow platform
+- **Flowise**: LangChain visual builder
+- **N8N**: Workflow automation platform
+- **EvoAI**: Custom AI integration
+
+**Event Integrations** (`src/api/integrations/event/`):
+- **WebSocket**: Real-time Socket.io connections
+- **RabbitMQ**: Message queue for async processing
+- **Amazon SQS**: Cloud-based message queuing
+- **NATS**: High-performance messaging system
+- **Pusher**: Real-time push notifications
+
+**Storage Integrations** (`src/api/integrations/storage/`):
+- **AWS S3**: Cloud object storage
+- **MinIO**: Self-hosted S3-compatible storage
+- Media file management and URL generation

 ### Database Schema Management
 - Separate schema files: `postgresql-schema.prisma` and `mysql-schema.prisma`
@@ -96,10 +130,12 @@ src/
 - Migration folders are provider-specific and auto-selected during deployment

 ### Authentication & Security
- API key-based authentication via `apikey` header
- Instance-specific authentication for WhatsApp connections
- Guards system for route protection
- Input validation using `class-validator`
+- **API key-based authentication** via `apikey` header (global or per-instance)
+- **Instance-specific tokens** for WhatsApp connection authentication
+- **Guards system** for route protection and authorization
+- **Input validation** using JSONSchema7 with RouterBroker `dataValidate`
+- **Rate limiting** and security middleware
+- **Webhook signature validation** for external integrations

 ## Important Implementation Details

@@ -136,24 +172,47 @@ Critical configurations:
 - `REDIS_ENABLED`: Enable Redis cache
 - `RABBITMQ_ENABLED`/`SQS_ENABLED`: Message queue options

-## Development Guidelines from Cursor Instructions
+## Development Guidelines

-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
+The project follows comprehensive development standards defined in `.cursor/rules/`:
+
+### Core Principles
+- **Always respond in Portuguese (PT-BR)** for user communication
+- **Follow established architecture patterns** (Service Layer, RouterBroker, etc.)
+- **Robust error handling** with retry logic and graceful degradation
+- **Multi-database compatibility** (PostgreSQL and MySQL)
+- **Security-first approach** with input validation and rate limiting
+- **Performance optimizations** with Redis caching and connection pooling
+
+### Code Standards
+- **TypeScript strict mode** with full type coverage
+- **JSONSchema7** for input validation (not class-validator)
+- **Conventional Commits** enforced by commitlint
+- **ESLint + Prettier** for code formatting
+- **Service Object pattern** for business logic
+- **RouterBroker pattern** for route handling with `dataValidate`
+
+### Architecture Patterns
+- **Multi-tenant isolation** at database and instance level
+- **Event-driven communication** with EventEmitter2
+- **Microservices integration** pattern for external services
+- **Connection pooling** and lifecycle management
+- **Caching strategy** with Redis primary and Node-cache fallback

 ## 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
+Currently, the project has minimal formal testing infrastructure:
+- **Manual testing** is the primary approach
+- **Integration testing** in development environment
+- **No unit test suite** currently implemented
+- Test files can be placed in `test/` directory as `*.test.ts`
+- Run `npm test` for watch mode development testing
+
+### Recommended Testing Strategy
+- Focus on **critical business logic** in services
+- **Mock external dependencies** (WhatsApp APIs, databases)
+- **Integration tests** for API endpoints
+- **Manual testing** for WhatsApp connection flows

 ## Deployment Considerations