Evo CRM Backend

Conversations, contacts, inboxes and messaging backend for the Evo CRM Community.

Website · Documentation · Community · Support

---

About

Evo CRM Backend is the core API of the Evo CRM Community customer support platform. Built with Ruby on Rails 7.1 (API mode), it manages conversations, contacts, messages, inboxes, and integrations across multiple communication channels (WhatsApp, Email, Web Widget, and more).

It exposes a comprehensive RESTful API and supports real-time messaging via ActionCable WebSockets.

Part of the Evo CRM Community

Evo CRM Backend is part of the Evo CRM Community ecosystem maintained by Evolution Foundation. To use the full stack, clone the umbrella repository with submodules:

git clone --recurse-submodules git@github.com:evolution-foundation/evo-crm-community.git

The Community Edition is single-tenant by design — one account, no multi-tenancy overhead, no super-admin, no billing or plans. All limits are removed and features are unlocked by default.

---

Tech Stack

Component	Technology
Backend	Ruby on Rails 7.1 (API mode)
Ruby	3.4.4
Database	PostgreSQL
Cache & Jobs	Redis + Sidekiq
Real-time	ActionCable (WebSocket)
Authentication	Bearer token via evo-auth-service-community
File storage	AWS S3, Google Cloud Storage, Azure Blob

---

Quick Start

Prerequisites

• Ruby 3.4.4
• PostgreSQL 12+
• Redis 6+
• pnpm (optional, for convenience scripts)

Installation

git clone git@github.com:evolution-foundation/evo-ai-crm-community.git
cd evo-ai-crm-community

# Install dependencies
bundle install
pnpm install  # Optional — for convenience scripts

# Setup database
bundle exec rails db:setup
bundle exec rails db:migrate

Running

# Using pnpm (recommended)
pnpm dev          # Rails + Sidekiq
pnpm start        # Rails only
pnpm sidekiq      # Sidekiq only

# Using Overmind / Foreman
overmind start -f Procfile.dev

# Manual
bundle exec rails server -p 3000
bundle exec sidekiq -C config/sidekiq.yml

The API will be available at http://localhost:3000.

---

Configuration

Copy .env.example to .env and configure:

# Database
DATABASE_URL=postgresql://localhost/evolution_crm_development

# Redis
REDIS_URL=redis://localhost:6379/0

# Optional: ScyllaDB for high-performance message storage
SCYLLA_ENABLED=true
SCYLLA_HOSTS=localhost
SCYLLA_PORT=9042
SCYLLA_KEYSPACE=evo_crm

# Frontend URL (CORS)
FRONTEND_URL=http://localhost:8080

# Storage (S3, GCS, Azure)
ACTIVE_STORAGE_SERVICE=local

See .env.example for the full list.

---

Available Scripts

Script	Description
pnpm dev	Start Rails + Sidekiq
pnpm start	Start Rails server
pnpm test	Run RSpec tests
pnpm lint	Run RuboCop
pnpm lint:fix	Run RuboCop with auto-fix
pnpm db:setup	Setup database
pnpm db:migrate	Run migrations
pnpm db:seed	Seed database
pnpm console	Rails console
pnpm sidekiq	Start Sidekiq worker

---

Architecture

API-only mode

The application runs in Rails API mode — no frontend views. The frontend is developed separately (evo-ai-frontend-community).

Service objects

Business logic is organized in service objects:

app/services/
├── base/
│   └── send_on_channel_service.rb
├── whatsapp/
│   └── message_processor_service.rb
└── crm/
    └── contact_sync_service.rb

Event-driven (Wisper)

Domain events are published for cross-cutting concerns:

• contact.created
• conversation.resolved
• message.sent

Background jobs (Sidekiq)

Heavy operations run asynchronously: external API calls, webhook processing, bulk operations.

---

API

Base URL

http://localhost:3000/api/v1

Authentication

Bearer tokens issued by evo-auth-service-community:

curl -H "Authorization: Bearer YOUR_TOKEN" \
     http://localhost:3000/api/v1/conversations

Documentation

Swagger UI available at http://localhost:3000/swagger.

For full API documentation, see docs.evolutionfoundation.com.br.

---

Features

• Real-time messaging via ActionCable WebSockets
• Multi-channel support (WhatsApp, Email, Web Widget, and more)
• RESTful API with comprehensive Swagger documentation
• High-performance messages with optional ScyllaDB (<1ms latency)
• Background jobs with Sidekiq
• Event-driven architecture for extensibility
• File storage support for S3, GCS, Azure Blob
• Rich message templates with drag-and-drop editor

---

Testing

# All tests
pnpm test
# or
bundle exec rspec

# Specific file
bundle exec rspec spec/models/contact_spec.rb

# Specific test
bundle exec rspec spec/models/contact_spec.rb:42

---

Linting

# Check
pnpm lint
# or
bundle exec rubocop

# Auto-fix
pnpm lint:fix
# or
bundle exec rubocop -a

---

Docker

docker-compose build
docker-compose up

# Specific services
docker-compose up backend worker

---

Documentation

Resource	Link
Website	evolutionfoundation.com.br
Documentation	docs.evolutionfoundation.com.br
Community	evolutionfoundation.com.br/community
Swagger	http://localhost:3000/swagger
Changelog	CHANGELOG.md
Contributing	CONTRIBUTING.md
Security	SECURITY.md

---

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines on how to submit issues, propose features, and open pull requests.

Join our community to discuss ideas and collaborate.

---

Security

For security issues, do not open a public issue. Email suporte@evofoundation.com.br or use GitHub's private vulnerability reporting. See SECURITY.md for details.

---

License

Evo CRM Backend is licensed under the Apache License 2.0. See LICENSE for details.

Trademarks

"Evolution Foundation", "Evolution" and "Evo CRM Backend" are trademarks of Evolution Foundation. See TRADEMARKS.md for the brand assets policy.

Third-party attributions are documented in NOTICE.

---

Made by Evolution Foundation · © 2026