A2UI - Documento Técnico Completo¶
Sistema de Gestão Empresarial com Inteligência Artificial¶
Versão: 1.0
Data: 01 de Fevereiro de 2026
Status: Especificação Técnica
Sumário¶
- Introdução
- Visão Geral do Sistema
- Arquitetura Técnica
- Módulos do Sistema
- Sistema de Autenticação
- Chat com Inteligência Artificial
- Roteamento de Mensagens
- Componentes Web2UI
- Integrações
- Banco de Dados
- Configuração e Personalização
- Interface do Usuário
- Fluxos de Trabalho
- Segurança
- Implantação
- Requisitos Técnicos
1. Introdução¶
1.1 Propósito¶
O A2UI é uma plataforma de gestão empresarial que utiliza inteligência artificial como interface principal de interação. O sistema foi projetado para escritórios de advocacia e empresas de serviços, permitindo a gestão de clientes, leads, cobranças e base de conhecimento através de um agente conversacional integrado.
1.2 Escopo¶
O sistema abrange:
- Gestão de usuários e permissões
- Dashboard analítico com métricas em tempo real
- Cadastro e gerenciamento de clientes
- Pipeline de captação de leads
- Sistema de cobrança automatizada
- Chat interno com inteligência artificial
- Base de conhecimento com busca semântica
- Integração com WhatsApp para atendimento externo
- Armazenamento e processamento de documentos
1.3 Definições¶
| Termo | Definição |
|---|---|
| Agente | Instância do Clawdbot configurada para um propósito específico |
| Web2UI | Componentes de interface renderizados dinamicamente pelo agente |
| Vault | Repositório de documentos em formato Markdown (Obsidian) |
| Knowledge Graph | Grafo de conhecimento armazenado no Neo4j |
| Session | Conversa persistente entre usuário e agente |
1.4 Princípios de Design¶
O sistema foi concebido seguindo o paradigma "Agent-First", onde:
- O agente de IA é o intermediário principal entre o usuário e o sistema
- Formulários são gerados dinamicamente conforme a necessidade
- O processamento de dados é feito com inteligência contextual
- A interface tradicional coexiste com a interface conversacional
2. Visão Geral do Sistema¶
2.1 Arquitetura Conceitual¶
┌─────────────────────────────────────────────────────────────────────┐
│ CAMADA DE APRESENTAÇÃO │
│ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ INTERFACE WEB (Next.js) │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │ │
│ │ │Dashboard │ │ Clientes │ │ Leads │ │ Chat Sidebar │ │ │
│ │ │ │ │ │ │ │ │ (Presente em │ │ │
│ │ │ │ │ │ │ │ │ todas as páginas│ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────────────┘ │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ CANAL WHATSAPP │ │
│ │ Atendimento a: Equipe | Clientes | Leads | Devedores │ │
│ └────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ CAMADA DE INTELIGÊNCIA │
│ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ CLAWDBOT GATEWAY │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ Agente │ │ Agente │ │ Agente │ │ │
│ │ │ Interno │ │ Cliente │ │ Cobrança │ ... │ │
│ │ │ (Dani) │ │ Support │ │ (Rebecca) │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ │ │ │
│ │ Capacidades: Linguagem Natural | Formulários Dinâmicos | │ │
│ │ Processamento de Documentos | Web2UI │ │
│ └────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ CAMADA DE DADOS │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ │
│ │ PostgreSQL │ │ Neo4j │ │ MinIO │ │ Obsidian │ │
│ │ │ │ │ │ │ │ Vault │ │
│ │ Dados │ │ Knowledge │ │ Arquivos │ │ │ │
│ │ Estruturados│ │ Graph │ │ e Docs │ │ Markdown │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ └────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
2.2 Componentes Principais¶
| Componente | Tecnologia | Função |
|---|---|---|
| Frontend | Next.js 14 + shadcn/ui | Interface web responsiva |
| Autenticação | NextAuth.js | Gestão de sessões e permissões |
| IA | Clawdbot + Claude | Processamento de linguagem natural |
| Banco Relacional | PostgreSQL | Dados estruturados |
| Grafo | Neo4j | Relacionamentos e busca semântica |
| Storage | MinIO | Armazenamento de arquivos |
| Documentos | Obsidian Vault | Base de conhecimento em Markdown |
| Transcrição | Whisper | Conversão de áudio para texto |
| Mensageria | WhatsApp (Baileys) | Comunicação externa |
3. Arquitetura Técnica¶
3.1 Stack Tecnológica¶
Frontend: - Next.js 14 (App Router) - React 18 - TypeScript - Tailwind CSS - shadcn/ui (preset Vega) - @assistant-ui (componentes de chat) - @elevenlabs-ui (interface de áudio)
Backend: - Next.js API Routes - Clawdbot Gateway - Node.js 20+
Bancos de Dados: - PostgreSQL 15+ (dados relacionais) - Neo4j 5+ (grafo de conhecimento) - Redis (cache e filas)
Armazenamento: - MinIO (S3-compatible) - Sistema de arquivos (Vault)
Infraestrutura: - Docker / Docker Compose - Traefik (reverse proxy) - Syncthing (sincronização de arquivos)
3.2 Diagrama de Containers¶
┌─────────────────────────────────────────────────────────────────────┐
│ DOCKER HOST │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ traefik │ │ a2ui │ │ clawdbot │ │
│ │ :80/:443 │ │ :3000 │ │ :3456 │ │
│ │ │ │ │ │ │ │
│ │ Reverse │ │ Next.js │ │ AI Gateway │ │
│ │ Proxy │ │ App │ │ │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
│ └────────────────┼────────────────┘ │
│ │ │
│ ┌─────────────┐ ┌──────┴──────┐ ┌─────────────┐ │
│ │ postgres │ │ neo4j │ │ minio │ │
│ │ :5432 │ │ :7474/:7687 │ │ :9000 │ │
│ │ │ │ │ │ │ │
│ │ Database │ │ Graph DB │ │ Object │ │
│ │ │ │ │ │ Storage │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ redis │ │ syncthing │ │
│ │ :6379 │ │ :22000 │ │
│ │ │ │ │ │
│ │ Cache │ │ File Sync │ │
│ └─────────────┘ └─────────────┘ │
│ │
│ Volumes: │
│ - postgres_data │
│ - neo4j_data │
│ - minio_data │
│ - obsidian_vault │
│ - clawdbot_data │
│ │
└─────────────────────────────────────────────────────────────────────┘
3.3 Fluxo de Requisições¶
Cliente (Browser)
│
▼
┌─────────────┐
│ Traefik │ ─── SSL Termination
└──────┬──────┘ Rate Limiting
│
├─── /api/* ────────────┐
│ │
▼ ▼
┌─────────────┐ ┌─────────────┐
│ Next.js │ │ Next.js │
│ (Pages) │ │ (API) │
└─────────────┘ └──────┬──────┘
│
┌──────────┼──────────┐
│ │ │
▼ ▼ ▼
┌──────────┐ ┌────────┐ ┌────────┐
│ Clawdbot │ │Postgres│ │ MinIO │
└──────────┘ └────────┘ └────────┘
4. Módulos do Sistema¶
4.1 Dashboard¶
O módulo de Dashboard apresenta uma visão consolidada das métricas e atividades do sistema.
Funcionalidades: - Widgets de métricas em tempo real - Gráficos de tendências - Lista de atividades recentes - Calendário de compromissos - Alertas e notificações
Widgets Disponíveis:
| Widget | Tipo | Fonte de Dados |
|---|---|---|
| Total de Clientes | Métrica | PostgreSQL |
| Processos Ativos | Métrica | Neo4j |
| Cobranças Pendentes | Métrica + Valor | PostgreSQL |
| Leads no Pipeline | Métrica | PostgreSQL |
| Documentos Processados | Métrica | MinIO |
| Clientes por Mês | Gráfico de Linha | PostgreSQL |
| Processos por Status | Gráfico de Pizza | Neo4j |
| Próximas Audiências | Tabela | PostgreSQL |
| Atividade Recente | Timeline | Logs |
| Agenda da Semana | Calendário | PostgreSQL |
4.2 Gestão de Clientes¶
O módulo de Clientes permite o cadastro e gerenciamento completo de clientes pessoa física e jurídica.
Funcionalidades: - Lista de clientes com busca e filtros - Cadastro via formulário ou via agente - Ficha completa do cliente - Upload e gestão de documentos - Histórico de interações - Processos vinculados - Agendamento de reuniões
Campos do Cadastro (Pessoa Física):
| Campo | Tipo | Obrigatório |
|---|---|---|
| Nome Completo | Texto | Sim |
| CPF | Texto (validado) | Sim |
| RG | Texto | Não |
| Data de Nascimento | Data | Não |
| Telefone | Texto | Sim |
| Não | ||
| Endereço | Objeto | Não |
| Filiação | Objeto | Não |
| Documentos | Arquivos | Não |
4.3 Pipeline de Leads¶
O módulo de Leads implementa um funil de vendas visual para acompanhamento de potenciais clientes.
Estágios do Pipeline:
┌─────────┐ ┌─────────┐ ┌───────────┐ ┌──────────┐ ┌───────────┐ ┌───────────┐
│ NOVO │ → │CONTATO │ → │QUALIFICADO│ → │ PROPOSTA │ → │NEGOCIAÇÃO │ → │CONVERTIDO │
│ │ │ INICIAL │ │ │ │ │ │ │ │ / PERDIDO │
└─────────┘ └─────────┘ └───────────┘ └──────────┘ └───────────┘ └───────────┘
Funcionalidades: - Visualização Kanban do pipeline - Drag-and-drop entre estágios - Captura automática via WhatsApp - Qualificação assistida por IA - Automação de follow-up - Conversão para cliente
4.4 Sistema de Cobranças¶
O módulo de Cobranças gerencia o processo de recuperação de créditos com automação via agente especializado.
Status de Cobrança:
| Status | Descrição |
|---|---|
| Pendente | Dívida registrada, aguardando início da cobrança |
| Em Cobrança | Processo de cobrança ativo |
| Negociação | Devedor em tratativas para acordo |
| Acordo | Acordo firmado, aguardando pagamento |
| Pago | Dívida quitada |
| Inadimplente | Cobrança encerrada sem sucesso |
Funcionalidades: - Dashboard de cobranças - Histórico de tentativas de contato - Automação via WhatsApp (Agente Rebecca) - Geração de acordos - Relatórios de recuperação
4.5 Base de Conhecimento¶
O módulo de Conhecimento integra o Obsidian Vault e o Neo4j para gestão de documentos e busca semântica.
Funcionalidades: - Upload e processamento de documentos - Extração automática de metadados - Indexação no grafo de conhecimento - Busca por linguagem natural - Relacionamentos automáticos entre documentos
5. Sistema de Autenticação¶
5.1 Modelo de Usuários¶
O sistema implementa um modelo de controle de acesso baseado em papéis (RBAC).
Papéis Disponíveis:
| Papel | Descrição | Nível de Acesso |
|---|---|---|
| admin | Administrador do sistema | Total |
| manager | Gerente de equipe | Alto |
| member | Membro da equipe | Básico |
Permissões por Módulo:
| Módulo | Admin | Manager | Member |
|---|---|---|---|
| Dashboard | Completo | Completo | Limitado |
| Clientes | CRUD | CRUD | Atribuídos |
| Leads | CRUD | CRUD | Atribuídos |
| Cobranças | CRUD | Visualizar | - |
| Conhecimento | CRUD | CRUD | Leitura |
| Usuários | CRUD | - | - |
| Configurações | CRUD | - | - |
5.2 Criação do Administrador Inicial¶
O primeiro usuário administrador é criado automaticamente na inicialização do sistema, utilizando as credenciais definidas nas variáveis de ambiente:
5.3 Fluxo de Autenticação¶
┌─────────────────────────────────────────────────────────────────────┐
│ FLUXO DE LOGIN │
└─────────────────────────────────────────────────────────────────────┘
1. Usuário acessa /login
2. Insere e-mail e senha
3. Sistema valida credenciais no PostgreSQL
4. Se válido:
a. Cria sessão no NextAuth
b. Armazena token JWT
c. Registra último login
d. Redireciona para /dashboard
5. Se inválido:
a. Retorna erro
b. Incrementa contador de tentativas
c. Após 5 tentativas, bloqueia por 15 minutos
6. Chat com Inteligência Artificial¶
6.1 Conceito¶
O chat com IA é o componente central do sistema, presente em todas as páginas como uma sidebar colapsível. O agente, denominado "Dani" por padrão, é capaz de executar todas as operações do sistema através de linguagem natural.
6.2 Características¶
Persistência de Sessão: - A sessão do chat permanece ativa ao navegar entre páginas - O histórico da conversa é preservado - O contexto da página atual é injetado nas requisições
Gerenciamento de Sessões: - Criar nova sessão - Listar histórico de sessões - Renomear sessão - Excluir sessão - Alternar entre sessões
Entrada de Dados: - Texto digitado - Áudio gravado (transcrito via Whisper) - Arquivos anexados (processados e armazenados)
Saída de Dados: - Texto formatado em Markdown - Componentes Web2UI interativos - Links para documentos e páginas
6.3 Estrutura da Mensagem¶
interface ChatMessage {
id: string; // Identificador único
sessionId: string; // Sessão à qual pertence
role: 'user' | 'assistant' | 'system';
content: string; // Conteúdo textual
attachments?: { // Anexos enviados pelo usuário
type: 'file' | 'audio' | 'image';
name: string;
url: string;
mimeType: string;
size: number;
transcription?: string; // Transcrição de áudio
}[];
components?: { // Componentes Web2UI
type: string;
props: Record<string, any>;
actions?: Action[];
}[];
metadata?: { // Metadados da resposta
model: string;
processingTime: number;
sources: string[];
agentUsed: string;
};
createdAt: Date;
}
6.4 Interface do Chat¶
┌─────────────────────────────────────────────────────────────────────┐
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ [Avatar] Dani [+] [📋] [◀] │ │
│ │ Assistente Virtual │ │
│ ├─────────────────────────────────────────────────────────────────┤ │
│ │ Nome da Sessão: Cadastro de Clientes [✏️] │ │
│ ├─────────────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────┐ │ │
│ │ │ 👤 Preciso cadastrar um novo cliente │ │ │
│ │ └─────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────┐ │ │
│ │ │ 🤖 Claro! Vou gerar o formulário de cadastro. │ │ │
│ │ │ │ │ │
│ │ │ ┌───────────────────────────────────────────────────┐ │ │ │
│ │ │ │ 📝 CADASTRO DE CLIENTE │ │ │ │
│ │ │ │ ─────────────────────────────────────────────── │ │ │ │
│ │ │ │ Nome: [____________________________] │ │ │ │
│ │ │ │ CPF: [____________________________] │ │ │ │
│ │ │ │ Tel: [____________________________] │ │ │ │
│ │ │ │ Docs: [📎 Anexar arquivos] │ │ │ │
│ │ │ │ │ │ │ │
│ │ │ │ [Cadastrar Cliente] │ │ │ │
│ │ │ └───────────────────────────────────────────────────┘ │ │ │
│ │ └─────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ ├─────────────────────────────────────────────────────────────────┤ │
│ │ [📎] [🎤] [Digite sua mensagem... ] [➤] │ │
│ └─────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
Legenda:
[+] = Nova sessão
[📋] = Histórico de sessões
[◀] = Colapsar sidebar
[✏️] = Editar nome da sessão
[📎] = Anexar arquivo
[🎤] = Gravar áudio
[➤] = Enviar mensagem
7. Roteamento de Mensagens¶
7.1 Conceito¶
O sistema implementa roteamento inteligente de mensagens baseado na identificação do remetente. Cada tipo de contato é direcionado para um agente especializado com permissões e comportamento específicos.
7.2 Tipos de Contato¶
| Tipo | Descrição | Agente Designado |
|---|---|---|
| user (admin) | Administrador do sistema | a2ui-admin |
| user (member) | Membro da equipe | a2ui-internal |
| client | Cliente cadastrado | client-support |
| lead | Lead em prospecção | lead-nurture |
| debtor | Devedor em cobrança | cobrador |
| unknown | Contato não identificado | lead-nurture |
7.3 Fluxo de Roteamento WhatsApp¶
┌─────────────────────────────────────────────────────────────────────┐
│ MENSAGEM WHATSAPP RECEBIDA │
│ +55 XX XXXXX-XXXX │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ ROUTER │
│ │
│ SELECT type, reference_id, agent_id │
│ FROM contacts │
│ WHERE phone = '+55XXXXXXXXXX' │
│ │
└─────────────────────────────────────────────────────────────────────┘
│
┌──────────────────────────┼──────────────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ EQUIPE/ADMIN │ │ CLIENTE │ │ LEAD/NOVO │
│ │ │ │ │ │
│ Agente: │ │ Agente: │ │ Agente: │
│ assistant │ │ client-support │ │ lead-nurture │
│ │ │ │ │ │
│ Acesso: │ │ Acesso: │ │ Acesso: │
│ - Vault │ │ - Seus dados │ │ - Info geral │
│ - Neo4j │ │ - Processos │ │ - Agendamento │
│ - Tarefas │ │ - Documentos │ │ - Qualificação │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌─────────────────┐
│ DEVEDOR │
│ │
│ Agente: │
│ cobrador │
│ (Rebecca) │
│ │
│ Acesso: │
│ - Sua dívida │
│ - Negociação │
│ - 2ª via boleto │
└─────────────────┘
7.4 Fluxo de Roteamento Web¶
┌─────────────────────────────────────────────────────────────────────┐
│ MENSAGEM CHAT WEB │
│ (Usuário Autenticado) │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ VERIFICAÇÃO DE SESSÃO │
│ │
│ 1. Validar token NextAuth │
│ 2. Obter user.id, user.role, user.permissions │
│ 3. Obter contexto da página atual │
│ │
└─────────────────────────────────────────────────────────────────────┘
│
┌───────────────┴───────────────┐
│ │
▼ ▼
┌───────────────────┐ ┌───────────────────┐
│ ROLE = 'admin' │ │ ROLE = 'member' │
│ │ │ ROLE = 'manager' │
│ Agente: │ │ │
│ a2ui-admin │ │ Agente: │
│ │ │ a2ui-internal │
│ Permissões: │ │ │
│ Irrestrito │ │ Permissões: │
│ │ │ Baseado em role │
└───────────────────┘ └───────────────────┘
8. Componentes Web2UI¶
8.1 Conceito¶
Web2UI é o sistema de componentes dinâmicos que permite ao agente retornar interfaces interativas como parte de suas respostas. Esses componentes são renderizados no chat e podem conter ações que o usuário executa.
8.2 Tipos de Componentes¶
Card Exibe informações estruturadas sobre uma entidade.
{
type: 'card',
props: {
title: 'João da Silva',
subtitle: 'Cliente desde 2024',
image: 'https://...',
fields: [
{ label: 'CPF', value: '123.456.789-00' },
{ label: 'Telefone', value: '+55 41 99999-9999' }
]
},
actions: [
{ label: 'Ver Ficha', action: 'navigate', url: '/clients/123' },
{ label: 'Ligar', action: 'call', phone: '+5541999999999' }
]
}
Table Exibe dados tabulares com possibilidade de ações.
{
type: 'table',
props: {
title: 'Processos do Cliente',
columns: ['Número', 'Tipo', 'Status', 'Última Movimentação'],
rows: [
['0001234-56.2024', 'Trabalhista', 'Em andamento', '01/02/2026'],
['0005678-90.2024', 'Cível', 'Aguardando', '28/01/2026']
]
},
actions: [
{ label: 'Exportar PDF', action: 'export', format: 'pdf' }
]
}
Form Formulário dinâmico para coleta de dados.
{
type: 'form',
props: {
title: 'Cadastro de Cliente',
fields: [
{ name: 'name', type: 'text', label: 'Nome', required: true },
{ name: 'cpf', type: 'text', label: 'CPF', mask: 'cpf', required: true },
{ name: 'phone', type: 'tel', label: 'Telefone', required: true },
{ name: 'type', type: 'select', label: 'Tipo', options: ['PF', 'PJ'] },
{ name: 'docs', type: 'file', label: 'Documentos', multiple: true }
],
submitLabel: 'Cadastrar'
},
actions: [
{ label: 'submit', action: 'send_to_agent', intent: 'create_client' }
]
}
Alert Exibe mensagens de alerta ou informação.
{
type: 'alert',
props: {
variant: 'warning', // info | warning | error | success
title: 'Atenção',
description: 'Este cliente possui pendências financeiras.'
}
}
Confirm Solicita confirmação para ações importantes.
{
type: 'confirm',
props: {
title: 'Confirmar Exclusão',
message: 'Esta ação não pode ser desfeita. Deseja continuar?',
confirmLabel: 'Excluir',
cancelLabel: 'Cancelar'
},
actions: [
{ label: 'confirm', action: 'api', method: 'DELETE', endpoint: '/api/clients/123' },
{ label: 'cancel', action: 'dismiss' }
]
}
Chart Exibe gráficos e visualizações.
{
type: 'chart',
props: {
chartType: 'bar', // bar | line | pie | area
title: 'Clientes por Mês',
data: [
{ label: 'Jan', value: 10 },
{ label: 'Fev', value: 15 },
{ label: 'Mar', value: 8 }
]
}
}
8.3 Fluxo de Formulário Dinâmico¶
┌─────────────────────────────────────────────────────────────────────┐
│ PASSO 1: Usuário solicita ação │
│ │
│ Usuário: "Quero cadastrar um novo cliente" │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ PASSO 2: Agente gera formulário │
│ │
│ Agente retorna componente Web2UI do tipo 'form' com os campos │
│ necessários para o cadastro de cliente. │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ PASSO 3: Usuário preenche e envia │
│ │
│ O formulário é renderizado no chat. O usuário preenche os campos, │
│ anexa documentos se necessário, e clica em "Cadastrar". │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ PASSO 4: Dados enviados ao agente │
│ │
│ Os dados do formulário são enviados como mensagem estruturada: │
│ │
│ { │
│ "intent": "create_client", │
│ "data": { "name": "...", "cpf": "...", ... }, │
│ "attachments": [ { "url": "s3://...", ... } ] │
│ } │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ PASSO 5: Agente processa │
│ │
│ 1. Valida os dados recebidos │
│ 2. Processa documentos anexados (OCR, extração) │
│ 3. Salva no PostgreSQL │
│ 4. Cria documento no Vault │
│ 5. Sincroniza com Neo4j │
│ 6. Atualiza índices │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ PASSO 6: Agente responde com confirmação │
│ │
│ Agente retorna mensagem de sucesso com componente 'card' exibindo │
│ os dados do cliente cadastrado e ações disponíveis. │
└─────────────────────────────────────────────────────────────────────┘
9. Integrações¶
9.1 Clawdbot¶
O Clawdbot é o gateway de inteligência artificial que gerencia os agentes e processa as requisições.
Configuração de Agentes:
/root/.clawdbot/agents/
├── main/ # Agente principal (OWNER)
├── assistant/ # Equipe interna (WhatsApp)
├── archon/ # Processamento de documentos
├── cobrador/ # Cobrança (Rebecca)
├── a2ui-internal/ # Chat web (Dani)
├── a2ui-admin/ # Chat web (Admin)
├── client-support/ # WhatsApp (Clientes)
└── lead-nurture/ # WhatsApp (Leads)
Integração via API:
// Enviar mensagem para agente
POST /api/chat
{
"sessionId": "uuid",
"message": "texto da mensagem",
"attachments": [],
"context": {
"userId": "uuid",
"userRole": "member",
"currentPage": "/clients"
}
}
// Resposta
{
"id": "uuid",
"content": "resposta do agente",
"components": [...],
"metadata": {
"agentUsed": "a2ui-internal",
"processingTime": 1500
}
}
9.2 PostgreSQL¶
Banco de dados relacional para armazenamento de dados estruturados.
Conexão:
Tabelas Principais: - users - chat_sessions - chat_messages - clients - leads - debtors - contacts
9.3 Neo4j¶
Banco de dados em grafo para armazenamento de relacionamentos e busca semântica.
Conexão:
Labels Principais: - ClientePf / ClientePj - Documento - Processo - Tag - Entity
9.4 MinIO¶
Armazenamento de objetos compatível com S3 para arquivos e documentos.
Configuração:
Buckets: - clientes/ - Documentos de clientes organizados por CPF/CNPJ - documentos/ - Documentos gerais - uploads/ - Uploads temporários
9.5 Whisper¶
Serviço de transcrição de áudio para texto.
Provedores Suportados: - OpenAI Whisper API - Whisper Local (faster-whisper)
Fluxo:
9.6 Obsidian Vault¶
Repositório de documentos em formato Markdown com sincronização via Syncthing.
Estrutura:
obsidian-vault/
├── 10-19 Jurídico/
│ ├── 11 Petições/
│ ├── 12 Contratos/
│ └── 13 Processos/
├── 20-29 Comercial/
│ ├── 21 Clientes/
│ ├── 22 Fornecedores/
│ └── 23 Propostas/
├── 30-39 Financeiro/
│ ├── 31 Cobranças/
│ └── 32 Pagamentos/
├── _system/
│ └── schemas/
└── index.md
10. Banco de Dados¶
10.1 Modelo de Dados¶
-- Usuários do sistema
CREATE TABLE users (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
email VARCHAR(255) UNIQUE NOT NULL,
password_hash VARCHAR(255) NOT NULL,
name VARCHAR(255) NOT NULL,
phone VARCHAR(20),
role VARCHAR(50) DEFAULT 'member',
permissions JSONB DEFAULT '{}',
avatar_url TEXT,
is_active BOOLEAN DEFAULT true,
last_login_at TIMESTAMP,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
-- Sessões de chat
CREATE TABLE chat_sessions (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
user_id UUID REFERENCES users(id),
name VARCHAR(255),
agent_id VARCHAR(100),
message_count INTEGER DEFAULT 0,
last_message_at TIMESTAMP,
metadata JSONB DEFAULT '{}',
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
-- Mensagens do chat
CREATE TABLE chat_messages (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
session_id UUID REFERENCES chat_sessions(id) ON DELETE CASCADE,
role VARCHAR(20) NOT NULL,
content TEXT NOT NULL,
attachments JSONB DEFAULT '[]',
components JSONB DEFAULT '[]',
metadata JSONB DEFAULT '{}',
created_at TIMESTAMP DEFAULT NOW()
);
-- Clientes
CREATE TABLE clients (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name VARCHAR(255) NOT NULL,
phone VARCHAR(20),
email VARCHAR(255),
type VARCHAR(10) DEFAULT 'pf',
cpf_cnpj VARCHAR(20),
company VARCHAR(255),
assigned_to UUID REFERENCES users(id),
is_active BOOLEAN DEFAULT true,
notes TEXT,
metadata JSONB DEFAULT '{}',
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
-- Leads
CREATE TABLE leads (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name VARCHAR(255) NOT NULL,
phone VARCHAR(20) UNIQUE,
email VARCHAR(255),
source VARCHAR(100),
interest_area VARCHAR(100),
stage VARCHAR(50) DEFAULT 'new',
assigned_to UUID REFERENCES users(id),
notes TEXT,
metadata JSONB DEFAULT '{}',
converted_to_client_id UUID,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
-- Devedores
CREATE TABLE debtors (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name VARCHAR(255) NOT NULL,
phone VARCHAR(20),
email VARCHAR(255),
cpf_cnpj VARCHAR(20),
total_debt DECIMAL(15,2),
status VARCHAR(50) DEFAULT 'pending',
last_contact_at TIMESTAMP,
next_contact_at TIMESTAMP,
assigned_to UUID REFERENCES users(id),
metadata JSONB DEFAULT '{}',
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
-- Tabela de lookup de contatos
CREATE TABLE contacts (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
phone VARCHAR(20) UNIQUE NOT NULL,
type VARCHAR(50) NOT NULL,
reference_id UUID,
name VARCHAR(255),
metadata JSONB DEFAULT '{}',
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
-- Índices
CREATE INDEX idx_contacts_phone ON contacts(phone);
CREATE INDEX idx_contacts_type ON contacts(type);
CREATE INDEX idx_chat_sessions_user ON chat_sessions(user_id);
CREATE INDEX idx_chat_messages_session ON chat_messages(session_id);
CREATE INDEX idx_clients_phone ON clients(phone);
CREATE INDEX idx_leads_phone ON leads(phone);
CREATE INDEX idx_debtors_phone ON debtors(phone);
10.2 Função de Identificação de Contato¶
CREATE OR REPLACE FUNCTION identify_contact(p_phone VARCHAR)
RETURNS TABLE (
contact_type VARCHAR,
contact_id UUID,
contact_name VARCHAR,
agent_id VARCHAR
) AS $$
BEGIN
RETURN QUERY
SELECT
c.type,
c.reference_id,
c.name,
CASE c.type
WHEN 'user' THEN
CASE (SELECT role FROM users WHERE id = c.reference_id)
WHEN 'admin' THEN 'a2ui-admin'::VARCHAR
ELSE 'assistant'::VARCHAR
END
WHEN 'client' THEN 'client-support'::VARCHAR
WHEN 'lead' THEN 'lead-nurture'::VARCHAR
WHEN 'debtor' THEN 'cobrador'::VARCHAR
ELSE 'lead-nurture'::VARCHAR
END
FROM contacts c
WHERE c.phone = p_phone
LIMIT 1;
IF NOT FOUND THEN
RETURN QUERY SELECT
'unknown'::VARCHAR,
NULL::UUID,
NULL::VARCHAR,
'lead-nurture'::VARCHAR;
END IF;
END;
$$ LANGUAGE plpgsql;
11. Configuração e Personalização¶
11.1 Variáveis de Ambiente¶
O sistema foi projetado para ser totalmente configurável via variáveis de ambiente, permitindo a implantação em múltiplos clientes (white-label).
# ============================================
# IDENTIDADE DO SISTEMA
# ============================================
APP_NAME="Nome da Empresa"
APP_AGENT_NAME="Dani"
APP_DESCRIPTION="Sistema de Gestão com IA"
APP_LOGO_URL="/logo.png"
APP_FAVICON_URL="/favicon.ico"
APP_PRIMARY_COLOR="#171717"
APP_ACCENT_COLOR="#3b82f6"
# ============================================
# URLS
# ============================================
APP_BASE_URL=https://app.empresa.com
APP_API_URL=https://api.empresa.com
NEXTAUTH_URL=https://app.empresa.com
NEXTAUTH_SECRET=chave-secreta-gerada
# ============================================
# ADMINISTRADOR INICIAL
# ============================================
ADMIN_EMAIL=admin@empresa.com
ADMIN_PASSWORD=SenhaSegura@2026
ADMIN_NAME=Administrador
# ============================================
# BANCO DE DADOS
# ============================================
DATABASE_URL=postgresql://user:pass@host:5432/database
# ============================================
# NEO4J
# ============================================
NEO4J_URI=bolt://neo4j:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=senha
# ============================================
# MINIO
# ============================================
MINIO_ENDPOINT=http://minio:9000
MINIO_PUBLIC_URL=https://s3.empresa.com
MINIO_ACCESS_KEY=access_key
MINIO_SECRET_KEY=secret_key
MINIO_BUCKET_DOCS=documentos
MINIO_BUCKET_CLIENTS=clientes
# ============================================
# CLAWDBOT
# ============================================
CLAWDBOT_GATEWAY_URL=http://clawdbot:3456
CLAWDBOT_API_KEY=api_key
# Agentes por tipo de usuário
CLAWDBOT_AGENT_WEB_INTERNAL=a2ui-internal
CLAWDBOT_AGENT_WEB_ADMIN=a2ui-admin
CLAWDBOT_AGENT_WA_MEMBER=assistant
CLAWDBOT_AGENT_WA_CLIENT=client-support
CLAWDBOT_AGENT_WA_LEAD=lead-nurture
CLAWDBOT_AGENT_WA_DEBTOR=cobrador
# ============================================
# WHISPER
# ============================================
WHISPER_PROVIDER=openai
OPENAI_API_KEY=sk-xxx
# ============================================
# MÓDULOS HABILITADOS
# ============================================
MODULE_DASHBOARD=true
MODULE_CLIENTS=true
MODULE_LEADS=true
MODULE_COLLECTIONS=true
MODULE_CALENDAR=true
MODULE_KNOWLEDGE=true
MODULE_WHATSAPP=true
# ============================================
# FEATURES
# ============================================
FEATURE_VOICE_INPUT=true
FEATURE_VOICE_OUTPUT=false
FEATURE_FILE_UPLOAD=true
FEATURE_WEB2UI_COMPONENTS=true
FEATURE_DYNAMIC_FORMS=true
# ============================================
# LIMITES
# ============================================
MAX_FILE_SIZE_MB=50
MAX_AUDIO_DURATION_SECONDS=300
MAX_SESSIONS_PER_USER=50
11.2 Módulos Configuráveis¶
Cada módulo pode ser habilitado ou desabilitado conforme a necessidade do cliente:
| Módulo | Variável | Descrição |
|---|---|---|
| Dashboard | MODULE_DASHBOARD | Painel de métricas e analytics |
| Clientes | MODULE_CLIENTS | Gestão de clientes |
| Leads | MODULE_LEADS | Pipeline de prospecção |
| Cobranças | MODULE_COLLECTIONS | Sistema de cobrança |
| Calendário | MODULE_CALENDAR | Agenda e compromissos |
| Conhecimento | MODULE_KNOWLEDGE | Base de conhecimento |
| MODULE_WHATSAPP | Integração com WhatsApp |
12. Interface do Usuário¶
12.1 Design System¶
O sistema utiliza os seguintes componentes e bibliotecas:
- Base: shadcn/ui com preset Vega
- Estilo: Neutral color scheme
- Fonte: Inter
- Ícones: Lucide React
- Tema: Light/Dark mode
Comando de Instalação:
npx shadcn@latest init \
--base radix \
--style vega \
--baseColor neutral \
--theme neutral \
--iconLibrary lucide \
--font inter
Bibliotecas Adicionais:
12.2 Layout Principal¶
┌─────────────────────────────────────────────────────────────────────┐
│ [Logo] Nome do Sistema [🔔] [User ▼] │
├─────────┬───────────────────────────────────────────────────────────┤
│ │ │
│ 📊 │ │
│ Dash │ │
│ │ ÁREA DE CONTEÚDO │
│ 👥 │ │
│Clientes │ (Página atual) │
│ │ │
│ 🎯 │ │
│ Leads │ │
│ │ ┌─────┤
│ 💰 │ │ 💬 │
│Cobranças│ │Chat │
│ │ │ │
│ 📚 │ │Dani │
│Conhecim.│ │ │
│ │ │ │
│ ⚙️ │ │ │
│ Config │ │ │
│ │ └─────┤
└─────────┴───────────────────────────────────────────────────────────┘
12.3 Estados do Chat Sidebar¶
Expandido:
┌────────────────────────────────────┐
│ [Avatar] Dani [+] [📋] [◀]│
├────────────────────────────────────┤
│ Sessão: Atendimento [✏️] │
├────────────────────────────────────┤
│ │
│ Mensagens... │
│ │
├────────────────────────────────────┤
│ [📎] [🎤] [__________] [➤] │
└────────────────────────────────────┘
Largura: 384px (w-96)
Colapsado:
13. Fluxos de Trabalho¶
13.1 Cadastro de Cliente via Chat¶
USUÁRIO SISTEMA (DANI)
│ │
│ "Quero cadastrar um cliente" │
│ ─────────────────────────────► │
│ │
│ │ Gera formulário Web2UI
│ │
│ Formulário de cadastro │
│ ◄───────────────────────────── │
│ │
│ Preenche dados + anexa docs │
│ Clica "Cadastrar" │
│ ─────────────────────────────► │
│ │
│ │ Valida dados
│ │ Processa documentos
│ │ Salva PostgreSQL
│ │ Cria no Vault
│ │ Sincroniza Neo4j
│ │ Upload MinIO
│ │
│ Card do cliente criado │
│ + Dados extraídos dos docs │
│ ◄───────────────────────────── │
│ │
13.2 Atendimento de Lead via WhatsApp¶
LEAD (WHATSAPP) SISTEMA
│ │
│ "Olá, gostaria de informações" │
│ ─────────────────────────────► │
│ │
│ │ Router identifica: unknown
│ │ Roteia para: lead-nurture
│ │ Cria registro em leads
│ │
│ "Olá! Sou a assistente..." │
│ "Como posso ajudar?" │
│ ◄───────────────────────────── │
│ │
│ "Preciso de um advogado │
│ trabalhista" │
│ ─────────────────────────────► │
│ │
│ │ Atualiza lead.interest_area
│ │ Move para stage: contacted
│ │
│ "Entendi! Nosso escritório..." │
│ "Posso agendar uma consulta?" │
│ ◄───────────────────────────── │
│ │
13.3 Cobrança Automatizada¶
SISTEMA DEVEDOR (WHATSAPP)
│ │
│ Cron identifica dívida vencida │
│ Roteia para: cobrador (Rebecca) │
│ │
│ "Bom dia, Sr. João..." │
│ "Identificamos pendência..." │
│ ─────────────────────────────► │
│ │
│ "Posso parcelar?" │
│ ◄───────────────────────────── │
│ │
│ Rebecca processa solicitação │
│ Gera opções de parcelamento │
│ │
│ "Sim! Temos as seguintes │
│ opções de parcelamento..." │
│ ─────────────────────────────► │
│ │
14. Segurança¶
14.1 Autenticação¶
- Senhas armazenadas com bcrypt (cost factor 12)
- Tokens JWT com expiração de 24 horas
- Refresh tokens com expiração de 7 dias
- Proteção contra brute force (rate limiting)
14.2 Autorização¶
- Verificação de permissões em todas as rotas de API
- Validação de permissões pelo agente antes de executar ações
- Contexto do usuário injetado em todas as requisições ao agente
14.3 Dados¶
- Conexões com banco de dados via SSL
- Arquivos sensíveis em buckets privados no MinIO
- Logs de auditoria para ações críticas
14.4 Comunicação¶
- HTTPS obrigatório em produção
- CORS configurado para domínios permitidos
- Headers de segurança via Traefik
15. Implantação¶
15.1 Requisitos de Infraestrutura¶
| Recurso | Mínimo | Recomendado |
|---|---|---|
| CPU | 2 cores | 4 cores |
| RAM | 8 GB | 16 GB |
| Disco | 50 GB SSD | 100 GB SSD |
| Rede | 100 Mbps | 1 Gbps |
15.2 Docker Compose¶
version: '3.8'
services:
a2ui:
build: .
ports:
- "3000:3000"
environment:
- DATABASE_URL=${DATABASE_URL}
- NEO4J_URI=${NEO4J_URI}
# ... demais variáveis
depends_on:
- postgres
- neo4j
- minio
- clawdbot
labels:
- "traefik.enable=true"
- "traefik.http.routers.a2ui.rule=Host(`app.${DOMAIN}`)"
clawdbot:
image: clawdbot/clawdbot:latest
volumes:
- clawdbot_data:/root/.clawdbot
- obsidian_vault:/root/obsidian-vault
environment:
- CLAWDBOT_CONFIG=/root/.clawdbot/clawdbot.json
postgres:
image: postgres:15
volumes:
- postgres_data:/var/lib/postgresql/data
environment:
- POSTGRES_DB=a2ui_db
- POSTGRES_USER=${DB_USER}
- POSTGRES_PASSWORD=${DB_PASSWORD}
neo4j:
image: neo4j:5
volumes:
- neo4j_data:/data
environment:
- NEO4J_AUTH=${NEO4J_USER}/${NEO4J_PASSWORD}
minio:
image: minio/minio
volumes:
- minio_data:/data
command: server /data --console-address ":9001"
environment:
- MINIO_ROOT_USER=${MINIO_ACCESS_KEY}
- MINIO_ROOT_PASSWORD=${MINIO_SECRET_KEY}
traefik:
image: traefik:v2.10
ports:
- "80:80"
- "443:443"
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
- traefik_certs:/letsencrypt
volumes:
postgres_data:
neo4j_data:
minio_data:
clawdbot_data:
obsidian_vault:
traefik_certs:
15.3 Processo de Deploy¶
- Clonar repositório
- Copiar
.env.examplepara.env - Configurar variáveis de ambiente
- Executar
docker compose up -d - Aguardar criação automática do admin
- Acessar via URL configurada
16. Requisitos Técnicos¶
16.1 Navegadores Suportados¶
| Navegador | Versão Mínima |
|---|---|
| Chrome | 90+ |
| Firefox | 88+ |
| Safari | 14+ |
| Edge | 90+ |
16.2 Dependências de Desenvolvimento¶
{
"dependencies": {
"next": "^14.0.0",
"react": "^18.2.0",
"typescript": "^5.0.0",
"@radix-ui/react-*": "latest",
"tailwindcss": "^3.4.0",
"next-auth": "^4.24.0",
"pg": "^8.11.0",
"neo4j-driver": "^5.0.0",
"minio": "^7.1.0",
"zod": "^3.22.0",
"lucide-react": "latest"
}
}
16.3 APIs Externas¶
| Serviço | Uso | Obrigatório |
|---|---|---|
| OpenAI | Whisper (transcrição) | Não* |
| Anthropic | Claude (via Clawdbot) | Sim |
*Pode ser substituído por Whisper local
Anexos¶
A. Glossário¶
| Termo | Definição |
|---|---|
| A2UI | Nome do sistema (Agent-to-UI) |
| Clawdbot | Gateway de IA que gerencia agentes |
| Web2UI | Sistema de componentes dinâmicos |
| Vault | Repositório de documentos Markdown |
| Session | Conversa persistente no chat |
B. Referências¶
- Next.js Documentation: https://nextjs.org/docs
- shadcn/ui: https://ui.shadcn.com
- Clawdbot: https://docs.clawd.bot
- Neo4j: https://neo4j.com/docs
- MinIO: https://min.io/docs
Fim do Documento
Este documento representa a especificação técnica completa do sistema A2UI na data de sua elaboração. Alterações e atualizações devem ser documentadas em versões subsequentes.