Omnichannel Sothis

Plataforma omnichannel para atendimento com foco inicial em WhatsApp. O sistema combina atendimento em tempo real, Agente Virtual para triagem, filas por especialidade, abertura ativa por template, agenda de contatos, painéis operacionais e administração de usuários/perfis.

O projeto foi construído para validar e evoluir um MVP de atendimento corporativo, com perfis de agente, supervisor e administrador.

Principais Recursos

• Login corporativo via LDAP/Active Directory.
• Estrutura para Microsoft OAuth / Entra ID.
• JWT próprio da aplicação com perfis e especialidades.
• Atendimento WhatsApp em tempo real via whatsapp-web.js.
• Socket.IO para atualização de chats/mensagens.
• Agente Virtual Sothis para triagem e roteamento.
• Fila por especialidade.
• Assumir, liberar, transferir e fechar atendimento.
• Abertura ativa com templates aprovados.
• Agenda de contatos com WhatsApp, telefone/SMS, email, etiqueta e observação.
• Painel do agente.
• Painel operacional do supervisor.
• Painel administrativo com usuários, acessos, templates, IA, canais e configurações.
• Conteúdos da IA e regras/travas.
• Migrations SQL versionadas.

Stack Técnica

Backend

• Node.js 20+ recomendado.
• NestJS ^11.1.
• TypeScript ^6.0.
• PostgreSQL via pg.
• Socket.IO ^4.8.
• whatsapp-web.js ^1.34.
• LDAP via ldapts.
• JWT via jsonwebtoken.
• Logs com winston.

Frontend

• React ^18.3.
• Vite ^5.4.
• React Router ^6.30.
• Socket.IO Client ^4.8.

Banco

• PostgreSQL 16 recomendado.
• O banco não é gerenciado pelo docker-compose.yml deste repositório.
• As migrations ficam em database/migrations.

Docker

O Docker Compose da raiz sobe somente:

• backend
• frontend

O banco deve ser externo ao compose: VM, banco corporativo, RDS, container separado ou PostgreSQL local gerenciado fora deste projeto.

Estrutura do Repositório

omnichannel/
├── backend/              # API NestJS e regras de negócio
├── frontend/             # Interface React/Vite
├── database/migrations/  # Migrations SQL
├── docs/                 # Wiki operacional e arquitetura
├── docker-compose.yml    # Sobe backend e frontend
└── README.md

Como Subir com Docker Compose

1. Configure .env.development na raiz com os dados do banco externo.
2. Garanta que o PostgreSQL externo esteja acessível a partir do container backend.
3. Suba backend e frontend:

docker compose up -d --build

URLs padrão:

• Frontend: http://localhost:4000
• Backend: http://localhost:4001

Health:

curl http://localhost:4001/health

Como Rodar em Desenvolvimento

Backend:

cd backend
npm install
npm run dev

Frontend:

cd frontend
npm install
npm run dev

URLs comuns:

• Frontend Vite: http://localhost:5173
• Backend: http://localhost:3001

Banco e Migrations

As migrations SQL estão em:

database/migrations

Elas representam a intenção de schema final/evolutivo do produto, mas o projeto ainda precisa de um runner formal para aplicar tudo em ordem em ambientes novos.

Para ambiente novo, antes de subir backend para uso real:

1. criar o banco PostgreSQL;
2. aplicar as migrations em ordem;
3. validar tabelas principais;
4. criar/atribuir usuário admin;
5. subir backend e frontend.

Detalhes em:

• Deploy e operação
• Database

Documentação

Wiki raiz:

• docs/README.md
• Deploy e operação
• Arquitetura geral
• Fluxos end-to-end
• Regras de negócio
• ADRs
• Ambientes
• Runbook

Backend:

• backend/docs/README.md
• Auth
• WhatsApp
• Admin
• Swagger/OpenAPI

Estado Atual e Próximos Passos

O produto já foi validado em demo com cliente final. Antes de produção real, os principais fechamentos são:

• implementar guards JWT no backend;
• validar autorização por perfil no backend;
• formalizar runner de migrations;
• configurar backup/restore do banco externo;
• persistir sessão WhatsApp em volume;
• criar Swagger com DTOs;
• adicionar testes nos fluxos críticos.