Pular para conteúdo

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

  1. Introdução
  2. Visão Geral do Sistema
  3. Arquitetura Técnica
  4. Módulos do Sistema
  5. Sistema de Autenticação
  6. Chat com Inteligência Artificial
  7. Roteamento de Mensagens
  8. Componentes Web2UI
  9. Integrações
  10. Banco de Dados
  11. Configuração e Personalização
  12. Interface do Usuário
  13. Fluxos de Trabalho
  14. Segurança
  15. Implantação
  16. 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:

  1. O agente de IA é o intermediário principal entre o usuário e o sistema
  2. Formulários são gerados dinamicamente conforme a necessidade
  3. O processamento de dados é feito com inteligência contextual
  4. 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
E-mail E-mail 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:

ADMIN_EMAIL=admin@empresa.com
ADMIN_PASSWORD=SenhaSegura@2026
ADMIN_NAME=Administrador

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:

postgresql://a2ui:password@postgres:5432/a2ui_db

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:

bolt://neo4j:7687

Labels Principais: - ClientePf / ClientePj - Documento - Processo - Tag - Entity

9.4 MinIO

Armazenamento de objetos compatível com S3 para arquivos e documentos.

Configuração:

Endpoint: http://minio:9000
Endpoint Público: https://s3.dominio.com

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:

Áudio (WebM/MP3) → Whisper → Texto → Agente

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
WhatsApp 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:

npx shadcn@latest registry add @assistant-ui
npx shadcn@latest registry add @elevenlabs-ui

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:

┌────┐
│ 💬 │
│    │
│ D  │
│    │
└────┘
Largura: 48px


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

  1. Clonar repositório
  2. Copiar .env.example para .env
  3. Configurar variáveis de ambiente
  4. Executar docker compose up -d
  5. Aguardar criação automática do admin
  6. 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.