🚀 Astra Campaign - Plataforma SaaS Multi-Tenant para Campanhas WhatsApp

Plataforma SaaS profissional multi-tenant para campanhas de WhatsApp em massa com IA integrada

🎯 Recursos • 🛠️ Instalação • 📚 Documentação • 🤝 Contribuição

📋 Sobre o Projeto

O Astra Campaign é uma plataforma SaaS multi-tenant completa e open-source para gerenciamento e execução de campanhas de WhatsApp em massa. Desenvolvido com arquitetura moderna, oferece recursos enterprise como isolamento total de dados por empresa, sistema de quotas, backup/restore automatizado, inteligência artificial para personalização de mensagens e suporte a múltiplos provedores WhatsApp (WAHA e Evolution API).

🔥 Open Source & SaaS Ready: Projeto totalmente gratuito com arquitetura multi-tenant pronta para comercialização. Sem ligação alguma com o WhatsApp oficial.

✨ Principais Diferenciais

🏢 Multi-Tenant (SaaS): Isolamento completo de dados por empresa
🔌 Dual Provider: Integração com WAHA API e Evolution API
🤖 IA Integrada: OpenAI e Groq para mensagens personalizadas
🎲 Randomização Inteligente: Textos, imagens, vídeos e arquivos aleatórios
🔄 Multi-Sessão com Failover: Distribuição inteligente de envios
💾 Backup & Restore: Sistema automatizado de backup e restauração
📊 Analytics Completo: Relatórios detalhados com exportação CSV
👥 Sistema de Roles: SUPERADMIN, ADMIN e USER
⚖️ Sistema de Quotas: Controle de limites por tenant
🎨 White Label: Personalização completa da marca
🐳 Deploy Simplificado: Docker Swarm com Traefik

🎯 Recursos Principais

🏢 Arquitetura Multi-Tenant (SaaS)

✅ Isolamento completo de dados por empresa (tenant)
✅ Sistema de quotas personalizáveis (usuários, contatos, campanhas, conexões)
✅ Gerenciamento centralizado via Super Admin
✅ White Label: Logo, favicon, cores e títulos personalizáveis
✅ Planos e limites configuráveis por tenant
✅ Associação many-to-many usuário-tenant
✅ Mensagens amigáveis para upgrade de plano

💾 Backup & Restore

✅ Backup automático agendado (cron configurável)
✅ Backup manual sob demanda
✅ Restauração completa do banco de dados
✅ Histórico de backups com metadados
✅ Armazenamento seguro em volumes Docker
✅ Gerenciamento via interface web

👥 Gerenciamento de Contatos

✅ CRUD completo de contatos
✅ Importação em massa via CSV
✅ Sistema de categorização com tags
✅ Validação de números telefônicos (formato E.164)
✅ Busca avançada e filtros inteligentes
✅ Paginação otimizada
✅ Isolamento por tenant

📱 Conexões WhatsApp (Dual Provider)

✅ WAHA API: Suporte completo com QR Code
✅ Evolution API: Integração nativa com Evolution
✅ Múltiplas sessões simultâneas por tenant
✅ QR Code automático com expiração
✅ Status em tempo real das conexões
✅ Gerenciamento simplificado de sessões
✅ Reconnect automático em falhas
✅ Seleção de provedor ao criar sessão

🎯 Campanhas Inteligentes

✅ Tipos de Mensagem: Texto, Imagem, Vídeo, Áudio, Documentos
✅ Sequências Complexas: Múltiplas mensagens em ordem
✅ Randomização: Textos, imagens, vídeos e arquivos aleatórios
✅ IA Generativa: OpenAI e Groq para personalização automática
✅ Variáveis Dinâmicas: {{nome}}, {{telefone}}, {{email}}, {{categoria}}, {{observacoes}}
✅ Multi-Sessão: Distribuição automática entre conexões
✅ Agendamento: Execução imediata ou programada
✅ Controles: Pausar, retomar, cancelar campanhas
✅ Rate Limiting: Delays configuráveis para evitar bloqueios
✅ Preview em Tempo Real: Visualização da mensagem antes do envio

🎲 Sistema de Randomização

✅ Textos Aleatórios: Pool de mensagens para variar conteúdo
✅ Imagens Aleatórias: Múltiplas imagens no pool
✅ Vídeos Aleatórios: Seleção aleatória de vídeos
✅ Arquivos Aleatórios: Documentos variados por envio
✅ Legendas Variadas: Textos diferentes para cada mídia
✅ Humanização: Evita detecção de envios automatizados

📊 Relatórios e Analytics

✅ Dashboard em tempo real
✅ Estatísticas detalhadas (enviadas, falharam, pendentes)
✅ Distribuição por sessão WhatsApp
✅ Análise de erros categorizada
✅ Exportação completa em CSV
✅ Timeline de execução
✅ Métricas por tenant

👤 Sistema de Usuários e Roles

✅ SUPERADMIN: Gerencia todos os tenants
✅ ADMIN: Gerencia seu tenant
✅ USER: Acesso limitado às funcionalidades
✅ Autenticação JWT segura
✅ Controle de acesso por tenant
✅ Hash bcrypt para senhas
✅ Associação many-to-many com tenants

⚙️ Configurações do Sistema

✅ Configurações globais (Super Admin)
✅ Configurações por tenant
✅ Integração WAHA configurável
✅ Integração Evolution API configurável
✅ Personalização visual (logo, favicon, cores, títulos)
✅ Chaves de API para IA (OpenAI/Groq) por tenant
✅ Gerenciamento de quotas por tenant
✅ Sistema de alertas e notificações

🔔 Sistema de Alertas e Monitoramento

✅ Alertas de quota (85% e 100% de uso)
✅ Monitoramento de saúde do sistema
✅ Notificações de falhas de conexão
✅ Dashboard de alertas ativos
✅ Auto-resolução de alertas antigos

🛠️ Tecnologias Utilizadas

🎨 Frontend

React 18 - Framework JavaScript moderno
TypeScript - Tipagem estática para JavaScript
Vite - Build tool ultra-rápida
Tailwind CSS - Framework CSS utilitário
React Hook Form + Zod - Validação de formulários
React Hot Toast - Notificações elegantes
React Router Dom - Roteamento SPA

⚡ Backend

Node.js 20 - Runtime JavaScript
Express - Framework web minimalista
TypeScript - Tipagem estática
Prisma ORM - Object-Relational Mapping
bcryptjs - Hash de senhas
jsonwebtoken - Autenticação JWT
express-validator - Validação de dados
libphonenumber-js - Normalização de telefones
node-cron - Agendamento de tarefas
socket.io - WebSocket para real-time

🗄️ Banco de Dados

PostgreSQL 16 - Banco de dados relacional
Redis 7 - Cache e filas
Prisma - ORM com type-safety

🐳 Infraestrutura

Docker & Docker Swarm - Containerização e orquestração
Traefik v2 - Proxy reverso e SSL automático
Nginx - Servidor web para frontend
Docker Hub - Imagens oficiais pré-construídas

🔌 Integrações

WAHA API - WhatsApp Web API
Evolution API - API alternativa para WhatsApp
OpenAI API - GPT para geração de conteúdo
Groq API - IA ultra-rápida

🚀 Instalação

📋 Pré-requisitos

Docker 20.10+
Docker Compose/Swarm
Traefik configurado (para produção)
Instância WAHA ou Evolution API rodando

🐳 Instalação via Docker (Recomendado)

Clone o repositório

git clone https://github.com/AstraOnlineWeb/astracampaign.git
cd astracampaign

Configure as variáveis de ambiente

# Edite o docker-stack.yml com suas configurações
nano docker-stack.yml

Principais variáveis:

environment:
  - DATABASE_URL=postgresql://postgres:postgres@postgres:5432/contacts
  - JWT_SECRET=sua-chave-secreta-muito-segura
  - DEFAULT_WAHA_HOST=https://seu-waha.com
  - DEFAULT_WAHA_API_KEY=sua-waha-api-key
  - DEFAULT_EVOLUTION_HOST=https://seu-evolution.com
  - DEFAULT_EVOLUTION_API_KEY=sua-evolution-api-key
  - DEFAULT_COMPANY_NAME=Sua Empresa
  - DEFAULT_PAGE_TITLE=Seu Sistema

Deploy no Docker Swarm

# Produção
docker stack deploy -c docker-stack.yml work

# Desenvolvimento local
docker-compose up -d

Verificar serviços

docker service ls
docker service logs -f work_backend

🛠️ Desenvolvimento Local

Backend

cd backend
npm install
npm run migrate:prod  # Rodar migrações e seed
npm run dev          # Servidor de desenvolvimento

Frontend

cd frontend
npm install
npm run dev          # Servidor de desenvolvimento (porta 3000)

⚙️ Configuração Inicial

Acesse o sistema: http://localhost ou seu domínio
Login padrão SUPERADMIN: [email protected] / Admin123
Login padrão ADMIN: [email protected] / Admin123
Configure provedores: Vá em Configurações e adicione WAHA/Evolution
Crie empresas: Como SUPERADMIN, crie novos tenants
Crie uma sessão WhatsApp: Na página de Conexões
Importe contatos: Via CSV ou manualmente
Crie sua primeira campanha: Na página de Campanhas

📚 Documentação

🔗 Endpoints da API

Autenticação

POST /api/auth/login - Login do usuário
POST /api/auth/logout - Logout do usuário

Tenants (SUPERADMIN)

GET /api/tenants - Listar todos os tenants
POST /api/tenants - Criar novo tenant
PUT /api/tenants/:id - Atualizar tenant
DELETE /api/tenants/:id - Excluir tenant
GET /api/tenants/:id - Detalhes do tenant

Contatos

GET /api/contatos - Listar contatos (com paginação/busca)
POST /api/contatos - Criar contato
PUT /api/contatos/:id - Atualizar contato
DELETE /api/contatos/:id - Excluir contato
POST /api/contatos/import - Importar CSV

Campanhas

GET /api/campaigns - Listar campanhas
POST /api/campaigns - Criar campanha
PATCH /api/campaigns/:id/toggle - Pausar/Retomar
DELETE /api/campaigns/:id - Excluir campanha
GET /api/campaigns/:id/report - Relatório detalhado

Sessões WhatsApp

GET /api/waha/sessions - Listar sessões
POST /api/waha/sessions - Criar sessão (WAHA ou Evolution)
DELETE /api/waha/sessions/:name - Remover sessão
POST /api/waha/sessions/:name/restart - Reiniciar

Backup & Restore

GET /api/backup/stats - Estatísticas de backup
POST /api/backup - Criar backup manual
POST /api/backup/restore/:filename - Restaurar backup
GET /api/backup/list - Listar backups disponíveis

Analytics

GET /api/analytics/overview - Visão geral do sistema
GET /api/analytics/campaigns - Métricas de campanhas
GET /api/analytics/sessions - Métricas de sessões

📊 Modelo de Dados

// Tenant (Empresa)
interface Tenant {
  id: string;
  slug: string;
  name: string;
  active: boolean;
  quotas: TenantQuota;
  settings: TenantSettings;
}

// Quotas do Tenant
interface TenantQuota {
  maxUsers: number;
  maxContacts: number;
  maxCampaigns: number;
  maxConnections: number;
}

// Contato
interface Contact {
  id: string;
  tenantId: string;
  nome: string;
  telefone: string; // E.164 format
  email?: string;
  categoriaId?: string;
  observacoes?: string;
}

// Campanha
interface Campaign {
  id: string;
  tenantId: string;
  nome: string;
  targetCategories: string[];
  sessionNames: string[];
  messageType: 'text' | 'image' | 'video' | 'audio' | 'document' | 'sequence';
  messageContent: MessageContent;
  randomize: boolean; // Randomizar conteúdo
  randomDelay: number;
  status: 'PENDING' | 'RUNNING' | 'COMPLETED' | 'PAUSED' | 'FAILED';
}

// Sessão WhatsApp
interface WhatsAppSession {
  id: string;
  tenantId: string;
  name: string;
  displayName?: string;
  status: string;
  provider: 'WAHA' | 'EVOLUTION';
  qr?: string;
}

🔧 Configuração Avançada

🔐 Variáveis de Ambiente

# Backend (.env)
DATABASE_URL=postgresql://user:pass@host:5432/db
REDIS_URL=redis://redis:6379
JWT_SECRET=sua-chave-secreta-muito-segura
JWT_EXPIRES_IN=24h
DEFAULT_WAHA_HOST=http://waha:3000
DEFAULT_WAHA_API_KEY=sua-waha-api-key
DEFAULT_EVOLUTION_HOST=http://evolution:8080
DEFAULT_EVOLUTION_API_KEY=sua-evolution-api-key
DEFAULT_COMPANY_NAME=Astra Campaign
DEFAULT_PAGE_TITLE=Sistema de Gestão de Contatos

🐳 Docker Swarm Labels

# Traefik Labels para Produção
labels:
  - traefik.enable=true
  - traefik.http.routers.app.rule=Host(`seu-dominio.com`)
  - traefik.http.routers.app.tls=true
  - traefik.http.routers.app.tls.certresolver=letsencrypt

📝 Formato CSV para Importação

nome,telefone,email,categoria,observacoes
João Silva,+5511999999999,[email protected],Cliente VIP,Cliente preferencial
Maria Santos,+5511888888888,[email protected],Prospect,Interessada em produto X

🎲 Randomização de Conteúdo

Para usar randomização de mensagens, configure múltiplos conteúdos:

{
  "texts": [
    "Olá {{nome}}! Tudo bem?",
    "Oi {{nome}}, como vai?",
    "E aí {{nome}}?"
  ],
  "images": [
    "/uploads/image1.jpg",
    "/uploads/image2.jpg",
    "/uploads/image3.jpg"
  ],
  "captions": [
    "Confira essa promoção!",
    "Veja essa novidade!",
    "Aproveite essa oportunidade!"
  ]
}

🚀 Deploy em Produção

🔧 Build das Imagens

# Backend
cd backend
docker build --no-cache -t work-backend:latest .

# Frontend
cd frontend
npm run build
docker build -t work-frontend:latest .

# Push para registry (opcional)
docker tag work-backend:latest seu-registry/work-backend:latest
docker push seu-registry/work-backend:latest

📊 Monitoramento

# Status dos serviços
docker service ls

# Logs em tempo real
docker service logs -f work_backend
docker service logs -f work_frontend

# Restart de serviços
docker service update --force work_backend

# Verificar health
curl http://localhost:3001/api/health

💾 Backup Automatizado

Configure o cron de backup no painel de Super Admin:

Diário: 0 2 * * * (02:00 AM)
Semanal: 0 2 * * 0 (Domingo 02:00 AM)
Mensal: 0 2 1 * * (Dia 1 de cada mês 02:00 AM)

🤝 Contribuindo

Contribuições são muito bem-vindas! Este é um projeto open-source mantido pela comunidade.

🛠️ Como Contribuir

Fork o repositório
Crie uma branch para sua feature (git checkout -b feature/nova-feature)
Commit suas mudanças (git commit -m 'Adiciona nova feature')
Push para a branch (git push origin feature/nova-feature)
Abra um Pull Request

📝 Reportar Bugs

Use o sistema de Issues
Descreva o problema detalhadamente
Inclua logs relevantes
Especifique ambiente (OS, Docker version, etc.)

💡 Sugerir Features

Abra uma Issue com o label enhancement
Descreva a funcionalidade desejada
Explique o caso de uso

📄 Licença

Este projeto está licenciado sob a GNU Affero General Public License v3.0 (AGPLv3) - veja o arquivo LICENSE para detalhes.

⚖️ Termos de Uso

✅ Uso comercial permitido
✅ Modificação permitida
✅ Distribuição permitida
✅ Uso privado permitido
✅ Uso em rede/web permitido
⚠️ Copyleft forte: Modificações devem ser disponibilizadas sob a mesma licença
⚠️ Divulgação de código: Serviços web baseados no projeto devem disponibilizar o código fonte
❌ Sem garantias
❌ Sem responsabilidade dos autores

Importante: A licença AGPLv3 requer que qualquer versão modificada do software, incluindo aquelas usadas para fornecer serviços através de uma rede, tenha seu código fonte disponibilizado publicamente.

⚠️ Disclaimer

IMPORTANTE: Este projeto é independente e não possui ligação alguma com o WhatsApp oficial, Meta ou Facebook. Use por sua própria conta e risco, respeitando os termos de serviço do WhatsApp.

🔒 Recomendações de Uso

✅ Respeite os limites do WhatsApp
✅ Use delays apropriados entre mensagens (recomendado: 5-10 segundos)
✅ Use randomização para humanizar os envios
✅ Não envie spam
✅ Obtenha consentimento dos destinatários
✅ Mantenha o sistema atualizado
✅ Faça backups regulares

🙏 Agradecimentos

WAHA - API WhatsApp Web
Evolution API - API alternativa para WhatsApp
Prisma - ORM TypeScript
Tailwind CSS - Framework CSS
React - Biblioteca JavaScript
Comunidade Open Source - Por tornar projetos como este possíveis

📞 Suporte

💬 Comunidade

💬 Grupo WhatsApp - Comunidade aberta para discussões
💬 Discussions - Discussões técnicas no GitHub
🐛 Issues - Bugs e features

🛠️ Suporte Profissional

Precisa de ajuda para melhorar, customizar ou implementar o projeto?

📱 WhatsApp: +55 61 9 9687-8959

💼 Temos uma equipe especializada para:

✅ Customizações e melhorias
✅ Implementação e deploy completo
✅ Configuração de arquitetura SaaS
✅ Integração com outras APIs
✅ Desenvolvimento de features específicas
✅ Suporte técnico dedicado
✅ Consultoria em automação WhatsApp
✅ Treinamento e documentação

📚 Recursos Úteis

⭐ Se este projeto foi útil para você, considere dar uma estrela no GitHub! ⭐

Feito com ❤️ pela comunidade open-source

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
backend		backend
frontend		frontend
.env.example		.env.example
.gitignore		.gitignore
.mailmap		.mailmap
LICENSE		LICENSE
README.md		README.md
docker-stack.yml		docker-stack.yml

License

matteusmoreira/astracampaign

Folders and files

Latest commit

History

Repository files navigation