mirror of
https://github.com/EvolutionAPI/evolution-api.git
synced 2025-12-09 01:49:37 -06:00
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.
This commit is contained in:
Davidson Gomes
parent
a721beda3c
commit
81a991a62e
372
AGENTS.md
372
AGENTS.md
@ -1,41 +1,355 @@
|
||||
# Repository Guidelines
|
||||
# Evolution API - AI Agent Guidelines
|
||||
|
||||
This document provides comprehensive guidelines for AI agents (Claude, GPT, Cursor, etc.) working with the Evolution API codebase.
|
||||
|
||||
## Project Overview
|
||||
|
||||
**Evolution API** is a production-ready, multi-tenant WhatsApp API platform built with Node.js, TypeScript, and Express.js. It supports multiple WhatsApp providers and extensive integrations with chatbots, CRM systems, and messaging platforms.
|
||||
|
||||
## Project Structure & Module Organization
|
||||
- `src/` – TypeScript source. Key areas: `api/controllers`, `api/routes`, `api/services`, `api/integrations/{channel,chatbot,event,storage}`, `config`, `utils`, `exceptions`.
|
||||
- `prisma/` – Prisma schema and migrations. Provider folders: `postgresql-migrations/`, `mysql-migrations/`. Use `DATABASE_PROVIDER` to target the provider.
|
||||
- `dist/` – Build output; do not edit.
|
||||
- `public/` – Static assets.
|
||||
- `Docker*`, `docker-compose*.yaml` – Local stack and deployment helpers.
|
||||
|
||||
### Core Directories
|
||||
- **`src/`** – TypeScript source code with modular architecture
|
||||
- `api/controllers/` – HTTP route handlers (thin layer)
|
||||
- `api/services/` – Business logic (core functionality)
|
||||
- `api/routes/` – Express route definitions (RouterBroker pattern)
|
||||
- `api/integrations/` – External service integrations
|
||||
- `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)
|
||||
- `dto/` – Data Transfer Objects (simple classes, no decorators)
|
||||
- `guards/` – Authentication/authorization middleware
|
||||
- `types/` – TypeScript type definitions
|
||||
- `repository/` – Data access layer (Prisma)
|
||||
- **`prisma/`** – Database schemas and migrations
|
||||
- `postgresql-schema.prisma` / `mysql-schema.prisma` – Provider-specific schemas
|
||||
- `postgresql-migrations/` / `mysql-migrations/` – Provider-specific migrations
|
||||
- **`config/`** – Environment and application configuration
|
||||
- **`utils/`** – Shared utilities and helper functions
|
||||
- **`validate/`** – JSONSchema7 validation schemas
|
||||
- **`exceptions/`** – Custom HTTP exception classes
|
||||
- **`cache/`** – Redis and local cache implementations
|
||||
|
||||
### Build & Deployment
|
||||
- **`dist/`** – Build output (do not edit directly)
|
||||
- **`public/`** – Static assets and media files
|
||||
- **`Docker*`**, **`docker-compose*.yaml`** – Containerization and local development stack
|
||||
|
||||
## Build, Test, and Development Commands
|
||||
- `npm run build` – Type-check (tsc) and bundle with `tsup` to `dist/`.
|
||||
- `npm run start` – Run dev server via `tsx src/main.ts`.
|
||||
- `npm run dev:server` – Watch mode for local development.
|
||||
- `npm run start:prod` – Run compiled app from `dist/`.
|
||||
- `npm run lint` / `npm run lint:check` – Auto-fix and check linting.
|
||||
- Database (choose provider): `export DATABASE_PROVIDER=postgresql` (or `mysql`), then:
|
||||
- `npm run db:generate` – Generate Prisma client.
|
||||
- `npm run db:migrate:dev` – Apply dev migrations and sync provider folder.
|
||||
- `npm run db:deploy` – Apply migrations in non-dev environments.
|
||||
- `npm run db:studio` – Open Prisma Studio.
|
||||
- Docker: `docker-compose up -d` to start local services.
|
||||
|
||||
## Coding Style & Naming Conventions
|
||||
- TypeScript, 2-space indent, single quotes, trailing commas, 120-char max (Prettier).
|
||||
- Enforced by ESLint + Prettier; import order via `simple-import-sort`.
|
||||
- File names follow `feature.kind.ts` (e.g., `chat.router.ts`, `whatsapp.baileys.service.ts`).
|
||||
- Classes: PascalCase; functions/variables: camelCase; constants: UPPER_SNAKE_CASE.
|
||||
### Development Workflow
|
||||
```bash
|
||||
# Development server with hot reload
|
||||
npm run dev:server
|
||||
|
||||
# Direct execution for testing
|
||||
npm start
|
||||
|
||||
# Production build and run
|
||||
npm run build
|
||||
npm run start:prod
|
||||
```
|
||||
|
||||
### Code Quality
|
||||
```bash
|
||||
# Linting and formatting
|
||||
npm run lint # ESLint with auto-fix
|
||||
npm run lint:check # ESLint check only
|
||||
|
||||
# Commit with conventional commits
|
||||
npm run commit # Interactive commit with Commitizen
|
||||
```
|
||||
|
||||
### Database Management
|
||||
```bash
|
||||
# Set database provider first (CRITICAL)
|
||||
export DATABASE_PROVIDER=postgresql # or mysql
|
||||
|
||||
# Generate Prisma client
|
||||
npm run db:generate
|
||||
|
||||
# Development migrations (with provider sync)
|
||||
npm run db:migrate:dev # Unix/Mac
|
||||
npm run db:migrate:dev:win # Windows
|
||||
|
||||
# Production deployment
|
||||
npm run db:deploy # Unix/Mac
|
||||
npm run db:deploy:win # Windows
|
||||
|
||||
# Database tools
|
||||
npm run db:studio # Open Prisma Studio
|
||||
```
|
||||
|
||||
### Docker Development
|
||||
```bash
|
||||
# Start local services (Redis, PostgreSQL, etc.)
|
||||
docker-compose up -d
|
||||
|
||||
# Full development stack
|
||||
docker-compose -f docker-compose.dev.yaml up -d
|
||||
```
|
||||
|
||||
## Coding Standards & Architecture Patterns
|
||||
|
||||
### Code Style (Enforced by ESLint + Prettier)
|
||||
- **TypeScript strict mode** with full type coverage
|
||||
- **2-space indentation**, single quotes, trailing commas
|
||||
- **120-character line limit**
|
||||
- **Import order** via `simple-import-sort`
|
||||
- **File naming**: `feature.kind.ts` (e.g., `whatsapp.baileys.service.ts`)
|
||||
- **Naming conventions**:
|
||||
- Classes: `PascalCase`
|
||||
- Functions/variables: `camelCase`
|
||||
- Constants: `UPPER_SNAKE_CASE`
|
||||
- Files: `kebab-case.type.ts`
|
||||
|
||||
### Architecture Patterns
|
||||
|
||||
#### Service Layer Pattern
|
||||
```typescript
|
||||
export class ExampleService {
|
||||
constructor(private readonly waMonitor: WAMonitoringService) {}
|
||||
|
||||
private readonly logger = new Logger('ExampleService');
|
||||
|
||||
public async create(instance: InstanceDto, data: ExampleDto) {
|
||||
// Business logic here
|
||||
return { example: { ...instance, data } };
|
||||
}
|
||||
|
||||
public async find(instance: InstanceDto): Promise<ExampleDto | null> {
|
||||
try {
|
||||
const result = await this.waMonitor.waInstances[instance.instanceName].findData();
|
||||
return result || null; // Return null on not found (Evolution pattern)
|
||||
} catch (error) {
|
||||
this.logger.error('Error finding data:', error);
|
||||
return null; // Return null on error (Evolution pattern)
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Controller Pattern (Thin Layer)
|
||||
```typescript
|
||||
export class ExampleController {
|
||||
constructor(private readonly exampleService: ExampleService) {}
|
||||
|
||||
public async createExample(instance: InstanceDto, data: ExampleDto) {
|
||||
return this.exampleService.create(instance, data);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### RouterBroker Pattern
|
||||
```typescript
|
||||
export class ExampleRouter extends RouterBroker {
|
||||
constructor(...guards: any[]) {
|
||||
super();
|
||||
this.router.post(this.routerPath('create'), ...guards, async (req, res) => {
|
||||
const response = await this.dataValidate<ExampleDto>({
|
||||
request: req,
|
||||
schema: exampleSchema, // JSONSchema7
|
||||
ClassRef: ExampleDto,
|
||||
execute: (instance, data) => controller.createExample(instance, data),
|
||||
});
|
||||
res.status(201).json(response);
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### DTO Pattern (Simple Classes)
|
||||
```typescript
|
||||
// CORRECT - Evolution API pattern (no decorators)
|
||||
export class ExampleDto {
|
||||
name: string;
|
||||
description?: string;
|
||||
enabled: boolean;
|
||||
}
|
||||
|
||||
// INCORRECT - Don't use class-validator decorators
|
||||
export class BadExampleDto {
|
||||
@IsString() // ❌ Evolution API doesn't use decorators
|
||||
name: string;
|
||||
}
|
||||
```
|
||||
|
||||
#### Validation Pattern (JSONSchema7)
|
||||
```typescript
|
||||
import { JSONSchema7 } from 'json-schema';
|
||||
import { v4 } from 'uuid';
|
||||
|
||||
export const exampleSchema: JSONSchema7 = {
|
||||
$id: v4(),
|
||||
type: 'object',
|
||||
properties: {
|
||||
name: { type: 'string' },
|
||||
description: { type: 'string' },
|
||||
enabled: { type: 'boolean' },
|
||||
},
|
||||
required: ['name', 'enabled'],
|
||||
};
|
||||
```
|
||||
|
||||
## Multi-Tenant Architecture
|
||||
|
||||
### Instance Isolation
|
||||
- **CRITICAL**: All operations must be scoped by `instanceName` or `instanceId`
|
||||
- **Database queries**: Always include `where: { instanceId: ... }`
|
||||
- **Authentication**: Validate instance ownership before operations
|
||||
- **Data isolation**: Complete separation between tenant instances
|
||||
|
||||
### WhatsApp Instance Management
|
||||
```typescript
|
||||
// Access instance via WAMonitoringService
|
||||
const waInstance = this.waMonitor.waInstances[instance.instanceName];
|
||||
if (!waInstance) {
|
||||
throw new NotFoundException(`Instance ${instance.instanceName} not found`);
|
||||
}
|
||||
```
|
||||
|
||||
## Database Patterns
|
||||
|
||||
### Multi-Provider Support
|
||||
- **PostgreSQL**: Uses `@db.Integer`, `@db.JsonB`, `@default(now())`
|
||||
- **MySQL**: Uses `@db.Int`, `@db.Json`, `@default(now())`
|
||||
- **Environment**: Set `DATABASE_PROVIDER=postgresql` or `mysql`
|
||||
- **Migrations**: Provider-specific folders auto-selected
|
||||
|
||||
### Prisma Repository Pattern
|
||||
```typescript
|
||||
// Always use PrismaRepository for database operations
|
||||
const result = await this.prismaRepository.instance.findUnique({
|
||||
where: { name: instanceName },
|
||||
});
|
||||
```
|
||||
|
||||
## Integration Patterns
|
||||
|
||||
### Channel Integration (WhatsApp Providers)
|
||||
- **Baileys**: WhatsApp Web with QR code authentication
|
||||
- **Business API**: Official Meta WhatsApp Business API
|
||||
- **Evolution API**: Custom WhatsApp integration
|
||||
- **Pattern**: Extend base channel service classes
|
||||
|
||||
### Chatbot Integration
|
||||
- **Base classes**: Extend `BaseChatbotService` and `BaseChatbotController`
|
||||
- **Trigger system**: Support keyword, regex, and advanced triggers
|
||||
- **Session management**: Handle conversation state per user
|
||||
- **Available integrations**: EvolutionBot, OpenAI, Dify, Typebot, Chatwoot, Flowise, N8N, EvoAI
|
||||
|
||||
### Event Integration
|
||||
- **Internal events**: EventEmitter2 for application events
|
||||
- **External events**: WebSocket, RabbitMQ, SQS, NATS, Pusher
|
||||
- **Webhook delivery**: Reliable delivery with retry logic
|
||||
|
||||
## Testing Guidelines
|
||||
- No formal suite yet. Place tests under `test/` as `*.test.ts`.
|
||||
- Run `npm test` (watches `test/all.test.ts` if present). Prefer fast, isolated unit tests.
|
||||
|
||||
### Current State
|
||||
- **No formal test suite** currently implemented
|
||||
- **Manual testing** is the primary approach
|
||||
- **Integration testing** in development environment
|
||||
|
||||
### Testing Strategy
|
||||
```typescript
|
||||
// Place tests in test/ directory as *.test.ts
|
||||
// Run: npm test (watches test/all.test.ts)
|
||||
|
||||
describe('ExampleService', () => {
|
||||
it('should create example', async () => {
|
||||
// Mock external dependencies
|
||||
// Test business logic
|
||||
// Assert expected behavior
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### Recommended Approach
|
||||
- Focus on **critical business logic** in services
|
||||
- **Mock external dependencies** (WhatsApp APIs, databases)
|
||||
- **Integration tests** for API endpoints
|
||||
- **Manual testing** for WhatsApp connection flows
|
||||
|
||||
## Commit & Pull Request Guidelines
|
||||
- Conventional Commits enforced by commitlint. Use `npm run commit` (Commitizen).
|
||||
- Examples: `feat(api): add message status`, `fix(route): handle 404 on send`.
|
||||
- PRs: include clear description, linked issues, migration impact (provider), local run steps, and screenshots/logs where relevant.
|
||||
|
||||
### Conventional Commits (Enforced by commitlint)
|
||||
```bash
|
||||
# Use interactive commit tool
|
||||
npm run commit
|
||||
|
||||
# Commit format: type(scope): subject (max 100 chars)
|
||||
# Types: feat, fix, docs, style, refactor, perf, test, chore, ci, build, revert, security
|
||||
```
|
||||
|
||||
### Examples
|
||||
- `feat(api): add WhatsApp message status endpoint`
|
||||
- `fix(baileys): resolve connection timeout issue`
|
||||
- `docs(readme): update installation instructions`
|
||||
- `refactor(service): extract common message validation logic`
|
||||
|
||||
### Pull Request Requirements
|
||||
- **Clear description** of changes and motivation
|
||||
- **Linked issues** if applicable
|
||||
- **Migration impact** (specify database provider)
|
||||
- **Local testing steps** with screenshots/logs
|
||||
- **Breaking changes** clearly documented
|
||||
|
||||
## Security & Configuration
|
||||
- Copy `.env.example` to `.env`; never commit secrets.
|
||||
- Set `DATABASE_PROVIDER` before DB commands; see `SECURITY.md` for reporting vulnerabilities.
|
||||
|
||||
### Environment Setup
|
||||
```bash
|
||||
# Copy example environment file
|
||||
cp .env.example .env
|
||||
|
||||
# NEVER commit secrets to version control
|
||||
# Set DATABASE_PROVIDER before database commands
|
||||
export DATABASE_PROVIDER=postgresql # or mysql
|
||||
```
|
||||
|
||||
### Security Best Practices
|
||||
- **API key authentication** via `apikey` header
|
||||
- **Input validation** with JSONSchema7
|
||||
- **Rate limiting** on all endpoints
|
||||
- **Webhook signature validation**
|
||||
- **Instance-based access control**
|
||||
- **Secure defaults** for all configurations
|
||||
|
||||
### Vulnerability Reporting
|
||||
- See `SECURITY.md` for security vulnerability reporting process
|
||||
- Contact: `contato@evolution-api.com`
|
||||
|
||||
## Communication Standards
|
||||
|
||||
### Language Requirements
|
||||
- **User communication**: Always respond in Portuguese (PT-BR)
|
||||
- **Code/comments**: English for technical documentation
|
||||
- **API responses**: English for consistency
|
||||
- **Error messages**: Portuguese for user-facing errors
|
||||
|
||||
### Documentation Standards
|
||||
- **Inline comments**: Document complex business logic
|
||||
- **API documentation**: Document all public endpoints
|
||||
- **Integration guides**: Document new integration patterns
|
||||
- **Migration guides**: Document database schema changes
|
||||
|
||||
## Performance & Scalability
|
||||
|
||||
### Caching Strategy
|
||||
- **Redis primary**: Distributed caching for production
|
||||
- **Node-cache fallback**: Local caching when Redis unavailable
|
||||
- **TTL strategy**: Appropriate cache expiration per data type
|
||||
- **Cache invalidation**: Proper invalidation on data changes
|
||||
|
||||
### Connection Management
|
||||
- **Database**: Prisma connection pooling
|
||||
- **WhatsApp**: One connection per instance with lifecycle management
|
||||
- **Redis**: Connection pooling and retry logic
|
||||
- **External APIs**: Rate limiting and retry with exponential backoff
|
||||
|
||||
### Monitoring & Observability
|
||||
- **Structured logging**: Pino logger with correlation IDs
|
||||
- **Error tracking**: Comprehensive error scenarios
|
||||
- **Health checks**: Instance status and connection monitoring
|
||||
- **Telemetry**: Usage analytics (non-sensitive data only)
|
||||
|
||||
|
||||
147
CLAUDE.md
147
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
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user