Tecnologia e arquitetura

Visão geral técnica do WayChat: do que ele é feito, como as peças se conectam e quais cuidados de segurança estão no desenho.

Esta página é para quem administra a plataforma, avalia a solução ou precisa responder dúvidas de segurança de um cliente. Ela não traz segredos, endereços internos nem chaves.

Visão geral

O WayChat é uma aplicação web única que atende vários canais (WhatsApp e chat do site) numa caixa de entrada compartilhada. A mesma versão do software roda para mais de uma empresa; a marca, o nome da empresa e os recursos opcionais mudam por configuração do ambiente. Os dados de cada empresa ficam separados por identificador de empresa em todas as tabelas.

Clientes ──► Canais (site, WhatsApp) ──► API NestJS ──► PostgreSQL
                                          │   │
                          Redis / BullMQ ◄┘   └──► Socket.IO ──► Painel (Vue 3)
                       (filas, timers, travas)      (tempo real)

Componentes

Camada	Tecnologia
Backend	Node.js 22 ou superior, NestJS 12, TypeScript 5.9 em módulos ESM (compilado com tsc), Express 5
Banco de dados	PostgreSQL, acessado com SQL direto (driver pg, sem ORM). O esquema é criado e atualizado de forma idempotente quando a aplicação sobe
Filas e timers	Redis com BullMQ 5
Tempo real	Socket.IO 4
Frontend do painel	Vue 3.5, Vite 8, SASS, Vue Router 4
Editor de fluxos	Vue Flow, sobre o Vue 3
Gráficos	Chart.js
Widget do chat do site	JavaScript puro (sem framework), isolado em Shadow DOM
Validação de entradas	Zod
IA	SDKs da OpenAI e da Anthropic; DeepSeek e Gemini por API compatível. As chaves são cadastradas pelo admin
E-mail	Nodemailer (SMTP), usado na redefinição de senha

Backend

O backend é uma API NestJS dividida em módulos (autenticação, atendimento, IA, métricas e outros). O módulo de atendimento concentra conversas, setores, equipe, canais, fluxos e integrações. A mesma aplicação também serve os arquivos do painel e o widget.js, o que permite rodar tudo em uma só origem.

Banco de dados

• O PostgreSQL guarda empresas, usuários, setores, horários, canais, contatos, conversas, mensagens, eventos, fluxos (com versões publicadas), base de conhecimento e métricas.
• A busca de texto usa recursos nativos do PostgreSQL (tsvector em português).
• O esquema é criado no boot, com instruções que podem ser executadas várias vezes sem efeito colateral, então uma atualização de versão não exige um passo manual de migração.

Filas, timers e travas (Redis e BullMQ)

O Redis tem três usos:

• Filas: envio de mensagens aos canais (com nova tentativa e espera crescente em caso de falha), tarefas de IA (triagem, resumo, transcrição, auditoria) e rotinas periódicas.
• Timers do fluxo: esperas, tempos limite de menus e perguntas e lembretes viram tarefas atrasadas. O estado do fluxo de cada conversa fica no banco, então sobrevive a reinícios.
• Travas: mensagens da mesma conversa são processadas em ordem, uma de cada vez.

Rotinas periódicas (a cada 30 segundos) cuidam de conversas adiadas que vencem, redistribuição da fila, escalonamento, lembretes de inatividade e avisos de SLA.

Tempo real (Socket.IO)

O painel abre uma conexão autenticada com o token do usuário. O servidor organiza as conexões em salas (por usuário, por empresa, por conversa) e envia eventos como nova mensagem, conversa atualizada, "digitando" e notificações. O visitante do chat do site tem um canal próprio, com credencial restrita à conversa dele.

Motor de fluxos

O motor executa a versão publicada do fluxo. Cada conversa tem uma sessão com o nó atual, as variáveis e o contador de tentativas. A publicação cria uma nova versão; conversas em andamento terminam na versão em que começaram.

Canais por camada de provedor

O resto do sistema fala com uma interface única de canal. Cada tipo de canal é um provedor que implementa quatro operações: informar suas capacidades (botões, listas, áudio), enviar mensagem, validar a assinatura do webhook e ler o webhook recebido.

Provedor	Observações
Chat do site	O widget conversa com a API pela web e por Socket.IO
WhatsApp via Evolution	Não oficial. Menus viram texto numerado
WhatsApp API oficial (Meta)	Botões e listas nativos. Webhook com assinatura HMAC-SHA256

Para adicionar um novo canal, basta implementar a interface; fluxos, filas e caixa de entrada continuam iguais.

Frontend

O painel é uma aplicação de página única (SPA) em Vue 3 com Vite e estilos em SASS, com layout responsivo (três colunas, gaveta ou tela única, conforme a largura). O tema claro e escuro e o menu recolhido são preferências guardadas no navegador. O editor de fluxos é visual e funciona no computador; no celular é só leitura.

Widget do chat

O widget.js é um único arquivo de JavaScript puro. Ele cria o balão dentro de um Shadow DOM, para que o CSS do site do cliente não interfira no chat (e vice-versa). Guarda um token da sessão do visitante no armazenamento local e carrega o cliente Socket.IO sob demanda.

Implantação

• Docker em imagem única: um Dockerfile de três estágios compila o painel (Vue + Vite), compila a API (TypeScript) e monta uma imagem final enxuta (Node 22 Alpine) que serve a API e os arquivos do painel na mesma porta.
• A imagem roda com usuário sem privilégios e tem verificação de saúde (health check) em um endpoint próprio.
• A configuração vem de variáveis de ambiente: banco, Redis, segredos, endereço público, marca e SMTP. A aplicação se recusa a subir se faltar um segredo obrigatório ou se ele for curto demais.
• O servidor espera estar atrás de um proxy reverso com HTTPS.

Segurança

Tema	Como é tratado
Autenticação	Senhas guardadas com hash scrypt e salt aleatório. Sessão por JWT assinado (HMAC-SHA256) com validade de 8 horas, e invalidação quando a senha muda ou o usuário sai
Papéis	Quatro papéis (dono, admin, supervisor, atendente) conferidos em cada rota. Cada pessoa só vê as conversas dos setores a que pertence, salvo admins
Webhooks	WhatsApp oficial: assinatura HMAC-SHA256 conferida em tempo constante com o segredo do app. Evolution: token secreto na URL. Corpo cru preservado para a conferência
Segredos	Chaves de IA, tokens de canais e credenciais de integrações ficam no banco cifrados com AES-256-GCM, com chave derivada (HKDF) e o contexto do registro como dado autenticado, o que impede reaproveitar um valor em outro lugar
Limites de taxa	Login (por IP e por conta), redefinição de senha, criação de sessão e envio de mensagens no chat do site, webhooks e proteção contra spam por contato
Cabeçalhos HTTP	Política de segurança de conteúdo (CSP), HSTS, X-Frame-Options, X-Content-Type-Options e política de permissões restritiva
Chat do site	Lista de domínios permitidos conferida no servidor, sem cookies (token por cabeçalho), tamanhos de corpo limitados
Chamadas externas	O nó HTTP do fluxo e as integrações só aceitam https e bloqueiam endereços internos (proteção contra SSRF). Expressões regulares dos fluxos passam por filtro contra padrões que travam o servidor
Mídia	Links de arquivos e fotos assinados e com validade
IA	Chaves cifradas, instruções de segurança nas chamadas e recursos desligados quando não há chave
LGPD	Registro do consentimento, exportação e eliminação do titular (admin), opt-out, bloqueio e limitação de contatos, e histórico de auditoria das ações sensíveis

Boas práticas de quem administra

Use HTTPS no proxy, guarde os segredos fora do código, troque-os se houver suspeita de vazamento e mantenha poucos admins.

Documentação para usuários

Se você procura como usar o painel, comece por Primeiros passos.