Architecture Overview

Evolution API Lite is built with a modular, service-oriented architecture that provides a robust abstraction layer for WhatsApp integrations. This document explains the key architectural components and how they work together to deliver a scalable WhatsApp API solution.

High-Level Architecture

The system follows a layered architecture pattern with clear separation of concerns:

Core Components

1. Application Bootstrap (main.ts)

The main.ts file serves as the application entry point and handles:

• Server Initialization: Sets up the Express.js server with middleware configuration
• CORS Configuration: Manages cross-origin resource sharing based on environment settings
• Dependency Injection: Initializes core services and repositories
• Error Handling: Implements global error handling with optional Sentry integration
• Provider Setup: Configures file providers for session management when enabled
• Database Connection: Establishes Prisma repository connections
• Event System: Initializes the event manager for real-time communications

Key responsibilities:

• Express server configuration with compression and JSON parsing
• Static file serving for store and public assets
• Global error middleware with webhook notifications
• HTTP/HTTPS server startup based on configuration

2. Dependency Injection Container (server.module.ts)

The server.module.ts acts as the central dependency injection container, orchestrating all services:

• Service Instantiation: Creates and configures all application services
• Controller Setup: Initializes controllers with their required dependencies
• Cache Management: Sets up Redis-based caching for instances and Baileys sessions
• Repository Configuration: Configures the Prisma repository for database operations
• Integration Setup: Initializes channel integrations (Baileys, Meta, Evolution)

Key services managed:

• WAMonitoringService - Instance lifecycle management
• EventManager - Real-time event processing
• CacheService - Redis-based caching
• PrismaRepository - Database operations
• Channel controllers for different WhatsApp providers

3. Instance State Management (monitor.service.ts)

The WAMonitoringService is the core orchestrator for WhatsApp instance lifecycle:

Instance Management:

• Creation & Initialization: Manages the creation of new WhatsApp instances
• Connection Monitoring: Tracks connection states (open, close, connecting)
• Lifecycle Events: Handles instance startup, shutdown, and cleanup
• Auto-cleanup: Implements configurable timeouts for inactive instances

Data Persistence:

• Database Integration: Saves instance metadata to PostgreSQL/MySQL
• Cache Management: Stores instance state in Redis for fast access
• Session Storage: Manages authentication sessions across restarts
• Provider Integration: Coordinates with external file providers

State Synchronization:

• Multi-source Loading: Loads instances from database, Redis, or providers
• Connection Recovery: Handles reconnection logic for dropped connections
• Event Broadcasting: Emits lifecycle events for external consumption

4. Channel Abstraction Layer (channel.service.ts)

The ChannelStartupService provides a unified interface for different WhatsApp providers:

Provider Abstraction:

• Unified Interface: Common API regardless of underlying provider (Baileys/Meta)
• Configuration Management: Handles provider-specific settings and authentication
• Connection Management: Abstracts connection logic across different providers

Instance Configuration:

• Settings Management: Handles instance-specific settings (auto-read, reject calls, etc.)
• Proxy Configuration: Manages proxy settings for instances
• Webhook Configuration: Configures webhook endpoints for event delivery

Data Operations:

• Message Handling: Provides unified message sending/receiving interface
• Contact Management: Abstracts contact and chat operations
• Media Processing: Handles media upload/download across providers

WhatsApp Provider Integration

Baileys Integration (whatsapp.baileys.service.ts)

The Baileys service implements the channel abstraction for the Baileys WhatsApp library:

• WebSocket Management: Handles WhatsApp Web protocol connections
• Authentication: Manages QR code and session-based authentication
• Message Processing: Implements all WhatsApp message types (text, media, buttons, etc.)
• Event Handling: Processes WhatsApp events and forwards them to the event system
• Session Persistence: Saves and restores authentication sessions

Data Flow

1. Instance Creation Flow

1. HTTP request received by Express router
2. Instance controller validates request data
3. Monitor service creates new instance record
4. Channel controller initializes provider-specific instance
5. Provider establishes WhatsApp connection
6. Instance state saved to database and cache
7. Success response returned to client

2. Message Sending Flow

1. Message request received by send message controller
2. Instance validation through monitor service
3. Message data processed and validated
4. Channel service routes to appropriate provider
5. Provider sends message via WhatsApp protocol
6. Message status tracked and stored
7. Webhook events triggered for status updates

3. Event Processing Flow

1. WhatsApp events received by provider
2. Events normalized through channel abstraction
3. Event manager processes and enriches event data
4. Events distributed via configured channels (webhooks, queues)
5. Event data optionally stored for audit purposes

Scalability Considerations

• Horizontal Scaling: Multiple instances can run behind a load balancer
• Cache Distribution: Redis provides shared state across instances
• Database Sharding: Prisma supports multiple database connections
• Event Distribution: RabbitMQ/SQS enables distributed event processing
• Session Persistence: External providers support distributed session storage

Security Architecture

• API Key Authentication: Global and instance-specific authentication
• Request Validation: Input validation at controller level
• Error Sanitization: Sensitive data removed from error responses
• Proxy Support: Built-in proxy support for network security
• Session Encryption: WhatsApp sessions encrypted at rest

This architecture provides a robust foundation for building WhatsApp integrations while maintaining flexibility for different deployment scenarios and scaling requirements.