Arquitetura¶
Visão Geral¶
CIBA (Craft Intelligent Bot Assistant) é um SaaS multi-tenant para atendimento automatizado via WhatsApp usando IA (Claude LLM), com escalação para atendentes humanos e portal administrativo.
┌─────────────────────────────────────────────────────────────────────────┐
│ CIBA Platform │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ WhatsApp │ │ Portal │ │ LLM APIs │ │
│ │ (usuário) │ │ (Blazor) │ │Claude/OpenAI │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────────────────────────┐ │
│ │ Evolution │───▶│ CIBA API │ │
│ │ API │◀───│ (.NET 8 Minimal APIs) │ │
│ └──────────────┘ └──────────────┬───────────────────┘ │
│ │ │
│ ┌──────────────┼──────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │PostgreSQL│ │ Redis │ │ R2 │ │
│ │ │ │ │ │ (Storage)│ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
Tech Stack¶
| Camada | Tecnologia |
|---|---|
| Backend | C# 12, .NET 8, Minimal APIs, MediatR (CQRS) |
| Frontend | Blazor WASM 8, MudBlazor 8 |
| Banco de Dados | PostgreSQL 17 + pgvector, EF Core 8 |
| Busca Semântica | pgvector (HNSW), OpenAI Embeddings |
| Cache | Redis 7 (StackExchange.Redis) |
| LLM | Claude API (Anthropic), OpenAI API |
| Evolution API v2.3.7 | |
| Storage | Cloudflare R2 (AWS S3 SDK) |
| Real-time | SignalR |
| Validação | FluentValidation 11 |
| Auth | JWT (HS256) |
Estrutura de Projetos¶
src/
├── Ciba.Domain/ → Entidades, enums, exceções (zero dependências externas)
├── Ciba.Shared/ → DTOs, validators, responses, rotas, Result pattern
├── Ciba.Infrastructure/ → EF Core, Redis, clients externos (Claude, Evolution, R2)
├── Ciba.Api/ → Minimal APIs, handlers MediatR, SignalR hub
└── Ciba.Web/ → Blazor WASM, pages, components, services
Dependências entre Projetos¶
- Domain não referencia nenhum outro projeto
- Shared é referenciado por Api e Web (DTOs, validators, rotas compartilhados)
- Web consome Api via HTTP (ApiClient)
Padrões Arquiteturais¶
Vertical Slices + CQRS¶
Cada feature é organizada em sua própria pasta com todos os artefatos relacionados:
Features/
├── Agents/
│ ├── Create/
│ │ ├── CreateAgentEndpoint.cs → Minimal API endpoint
│ │ └── CreateAgentHandler.cs → MediatR handler
│ ├── Update/
│ ├── Delete/
│ ├── GetAll/
│ ├── GetById/
│ └── AgentEndpoints.cs → Agregador de rotas
Result Pattern¶
Handlers retornam Result<T> para comunicação explícita de sucesso/erro:
public class Result<T>
{
public bool IsSuccess { get; }
public T? Value { get; }
public Error? Error { get; }
}
public class Error
{
public string Code { get; }
public string Message { get; }
public ErrorType Type { get; } // NotFound, Validation, Conflict, etc.
}
Multi-tenancy¶
- Query filters globais no
AppDbContextfiltram porTenantId TenantIdextraído do JWT viaITenantProvider- SuperAdmin (
TenantId = null) acessa todos os dados
Componentes Principais¶
Evolution API¶
Gateway de conexão com WhatsApp (não-oficial).
| Responsabilidade | Descrição |
|---|---|
| Gerenciar sessões | Mantém conexões WebSocket com WhatsApp |
| Receber mensagens | Captura mensagens via webhook |
| Enviar mensagens | Envia respostas para os contatos |
| Gerar QR code | Permite conexão/reconexão de sessões |
CIBA API¶
Núcleo do sistema. API única servindo webhook + portal.
| Feature | Descrição |
|---|---|
| Agents | CRUD de agentes com knowledge e mensagens customizadas |
| Instances | CRUD de instâncias WhatsApp + whitelist/blacklist |
| Conversations | Gestão de conversas e mensagens |
| Webhook | Processamento de eventos do Evolution |
| SignalR Hub | Atualizações real-time para o portal |
Portal Blazor¶
Interface administrativa para gestão do sistema.
| Funcionalidade | Descrição |
|---|---|
| Autenticação | Login com JWT |
| Gestão de agentes | Configuração completa + playground |
| Gestão de instâncias | Conexão WhatsApp + QR code |
| Conversas | Chat em tempo real com clientes |
| Dashboard | Visão geral do sistema |
Fluxo de Dados Principal¶
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ WhatsApp │────▶│ Evolution │────▶│ CIBA API │────▶│ LLM APIs │
│ (user) │ │ API │ │ │ │Claude/OpenAI│
└─────────────┘ └─────────────┘ └──────┬──────┘ └─────────────┘
│ │
┌─────────────────────┼───────────────────┤
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ PostgreSQL │ │ Redis │ │ OpenAI │
│ + pgvector │ │ │ │ Embeddings │
└─────────────┘ └─────────────┘ └─────────────┘
│
▼
┌─────────────┐
│ R2 │
│ (Storage) │
└─────────────┘
- Usuário envia mensagem no WhatsApp
- Evolution API recebe e dispara webhook
- CIBA API processa:
- Identifica instância pelo
sessionId - Recupera/cria conversa
- Busca semântica: gera embedding da mensagem e busca blocos relevantes (pgvector)
- Monta contexto com histórico + knowledge relevante
- Chama Claude/OpenAI API
- Salva mensagem no banco
- Notifica portal via SignalR
- Envia resposta de volta via Evolution
Segurança¶
| Camada | Proteção |
|---|---|
| Webhook Evolution | Processamento assíncrono via Redis Streams |
| Portal | JWT + refresh token |
| API | JWT obrigatório + filtro de tenant |
| Banco | Query filters globais |
Resiliência¶
| Componente | Estratégia |
|---|---|
| Claude/OpenAI API | Timeout 30s, retry com backoff |
| OpenAI Embeddings | Timeout 30s, retry com backoff, fallback para todos os blocos |
| Evolution API | Timeout 10s |
| Redis indisponível | Fallback para PostgreSQL |
| Webhook duplicado | Idempotência via WhatsAppMessageId |
| Busca semântica falha | Carrega todos os blocos de conhecimento |