Infraestrutura conversacional vertical · v1.1.0

Luna.AI

Conversa que vira operação controlada.

Plataforma para WhatsApp com Flow Runtime transacional, Conversational Engine LLM-driven, RAG tenant-aware e foundation para adapters de ERPs SMB brasileiros.

Em produção · DG Barbearia · 74+ dias Claude Sonnet 4.6 + Haiku 4.5 Foundation · Integration Hub Foundation · Vertical Packs flows-backend v1.1.0
DIAGNÓSTICO

Entre conversa e sistema de verdade.

PMEs brasileiras vendem e atendem pelo WhatsApp, mas os ERPs que sustentam a operação não foram desenhados para conversar. O resultado é gente copiando dado entre chat, agenda, estoque, financeiro e CRM.

Luna ocupa esse espaço: conversa natural na ponta, leitura confiável de contexto e caminho controlado para write-back quando o adapter estiver validado.

Canal

WhatsApp como balcão principal

Sistema

ERP nacional sem camada de IA

Automação

Fluxos fixos e pouco integrados

Lacuna

Agente que conversa, consulta dados e controla ações

22,7M
pequenas empresas SMB no Brasil operando via WhatsApp
SEBRAE / CNDL 2025
41%
das empresas usam alguma automação, quase sempre sem contexto vertical
Trend.com.br · Out/2025
74+
dias de operação contínua do DG, sem interrupção
desde março/2026
ARQUITETURA

Como uma mensagem
vira ação.

Seis camadas com fronteira clara. Cada uma faz uma coisa e faz bem.

  1. 1 · WhatsApp

    Evolution API · Twilio WABA institucional

  2. 2 · NLU híbrido

    regex + Haiku 4.5 / Sonnet 4.6 por contexto

  3. 3 · Flow Runtime

    transacional + estado preservado

  4. 4 · RAG tenant-aware

    admin_rag_documents · cosine · text-embedding-3-small

  5. 5 · Integration Hub

    foundation · interfaces + registry

  6. 6 · Adapters

    PrintWayy Fase 1 READ · Fase 2 aguarda credenciais

Camada 1

WhatsApp

Em produção

Entrada conversacional operacional via Evolution API. Twilio WABA permanece como opção suportada para cenários institucionais.

Camada 2

NLU híbrido

Em produção

Regex para atalhos; Claude Haiku 4.5 para NLU/classificação e Sonnet 4.6 para raciocínio quando o contexto exige.

Camada 3

Flow Runtime

Em produção

Runtime transacional node-based usado pela operação DG. State-aware NLU, confirmação e anti-reset rodam sem depender de árvore de decisão estática.

Camada 4

RAG tenant-aware

Hoje via admin_rag_documents, embeddings OpenAI text-embedding-3-small e similaridade cosine em memória no banco principal.

Camada 5

Integration Hub

Foundation

Foundation com interfaces por categoria (ERPAdapter, PaymentAdapter etc.) e registry para adapters concretos por tenant.

Camada 6

Adapters

PrintWayy é o primeiro adapter externo em desenvolvimento: Fase 1 concluída com 13 endpoints READ e 30 testes; writes ficam para Fase 2 após credenciais.

TOOL USE FORMAL
Em produção · luna-chat tools Em construção · PrintWayy Fase 2

Decisão estruturada,
ação confirmada.

O engine institucional já executa tools internas com loop tool_use/tool_result. Para adapters externos, o padrão plan → confirm → apply fica reservado à Fase 2.

Caso-alvo · PrintWayy Fase 2 (planejado)

printwayy.adapter.ts
// apps/flows-backend/src/integrations/adapters/printwayy.adapter.ts

const transferStockItemTool: AnthropicTool = {
  name: "printwayy_transfer_stock_item",
  description:
    "Transfere quantidade de item de estoque entre localizações no " +
    "PrintWayy. sourceCustomerPlaceId vazio = origem é o provedor. " +
    "destCustomerPlaceId vazio = destino é o provedor.",
  input_schema: {
    type: "object",
    properties: {
      stockItemId: { type: "string", format: "uuid" },
      quantity: { type: "integer", minimum: 1 },
      sourceCustomerPlaceId: { type: "string", format: "uuid" },
      destCustomerPlaceId: { type: "string", format: "uuid" }
    },
    required: ["stockItemId", "quantity"]
  }
};

Caso-alvo · fluxo de write PrintWayy

Sequência planejada para Fase 2: usuário, Sonnet 4.6, Flow Runtime, Adapter e Sistema externo. Usuário Sonnet 4.6 Runtime Adapter Sistema 1 · PLAN 2 · CONFIRM 3 · APPLY "Transfere 3 toners..." tool_use call preview estruturado "Pode confirmar" apply POST 200 OK ✓ "Registrado."

Tools institucionais em produção

registrar_lead, escalar_humano, oferecer_agenda e consultar_metricas_dg já rodam no luna-chat.

Writes externos ainda não entregues

PrintWayy Fase 1 cobre leitura. Writes e audit dedicado ficam para Fase 2 após credenciais reais.

Idempotency e validação

Request ID determinístico, Zod e retry seguro são requisitos definidos para a Fase 2 do adapter PrintWayy.

STACK

Decisões técnicas
defendidas.

Cada peça escolhida pra resolver um problema específico em produção. Sem stack-by-trend.

Node.js TypeScript Express Drizzle ORM PostgreSQL Redis cache/queue Anthropic Claude Sonnet 4.6 Haiku 4.5 Evolution API Twilio WABA Railway Vercel React Vite Tailwind CSS pnpm workspaces OpenAI embeddings text-embedding-3-small PrintWayy Fase 1 READ Vertical Packs foundation Node.js TypeScript Express Drizzle ORM PostgreSQL Redis cache/queue Anthropic Claude Sonnet 4.6 Haiku 4.5 Evolution API Twilio WABA Railway Vercel React Vite Tailwind CSS pnpm workspaces OpenAI embeddings text-embedding-3-small PrintWayy Fase 1 READ Vertical Packs foundation

01

Anthropic Claude com tool use formal

Plan-confirm-apply garante ação somente com confirmação explícita no Cockpit, antes de aplicar mudanças sensíveis.

02

RAG tenant-aware no Postgres

Documentos em admin_rag_documents, embeddings OpenAI text-embedding-3-small e similaridade cosine em memória.

03

Multi-tenant por identidade do cliente

Tenant aplicado nas consultas, no admin e nos fluxos. A base atual convive com UUID e slug por camada.

04

Routing por complexidade Haiku/Sonnet

Haiku 4.5 cobre NLU/classificação; Sonnet 4.6 cobre raciocínio e tool use no engine institucional.

05

React/Vite nas frentes principais

Frontends da plataforma rodam em React + Vite + Tailwind; esta landing dedicada usa Astro no Vercel.

06

Drizzle ORM + Postgres

Type-safe queries em build time. Migrations idempotentes. Compatível com Railway, Supabase, AWS RDS.

07

Evolution API self-hosted

Canal operacional dos tenants. Twilio WABA é a entrada institucional do luna-chat.

08

Zod em fronteiras implementadas

Validação em runtime já é padrão nas rotas. Os adapters externos devem seguir o mesmo contrato tipado.

INTEGRATION HUB
Foundation

Pense em MCP,
aplicado verticalmente.

A foundation do Integration Hub está implementada: interfaces por categoria (ERP, Payment, Calendar, CRM), registry por tenant e manifest declarativo. O primeiro adapter concreto — PrintWayy — está em desenvolvimento; a Fase 1 concluiu 13 endpoints READ com 30 testes e a Fase 2 aguarda credenciais reais.

1

Vertical declara

manifest.integrations[]

2

Hub resolve

config do tenant

3

Adapter conecta

Fase 1 READ

4

Sistema externo

GET validado; writes em Fase 2

Snippet 1 · Manifest do vertical (declarativo)

apps/verticals/outsourcing/manifest.ts
// apps/verticals/outsourcing/manifest.ts

import type { VerticalManifest } from '@/types/vertical-manifest';

export const manifest: VerticalManifest = {
  slug: 'outsourcing',
  name: 'Outsourcing de Impressão',
  industry: 'outsourcing',
  schemaPrefix: 'os_',

  integrations: [
    {
      name: 'printwayy',
      type: 'erp',
      required: false,
      capabilities: ['read'], // Fase 1 concluida; write entra na Fase 2
      configFields: [
        { key: 'api_key', type: 'secret', required: true },
        { key: 'company_id', type: 'string', required: true }
      ],
      adapterPath: '@adapters/printwayy.adapter'
    }
  ],

  customIntents: [
    'novo_chamado',
    'status_chamado',
    'consultar_estoque',
    'transferir_estoque',
    'consultar_fechamento',
    'consultar_contrato'
  ],

  ragAutoIndex: true,
  ragDocsPath: 'apps/verticals/outsourcing/skills'
};

Spec do adapter · Fase 1 READ

apps/flows-backend/.../printwayy.adapter.ts
// apps/flows-backend/src/integrations/adapters/printwayy.adapter.ts

export class PrintWayyAdapter implements ERPAdapter {
  // Fase 1: 13 endpoints READ cobertos por 30 testes.
  // Fase 2: writes depois de credenciais reais + audit dedicado.

  async readContractContext(
    input: PrintWayyReadInput
  ): Promise<IntegrationResult<PrintWayyReadResult>> {
    // Validação Zod em runtime
    const parsed = PrintWayyReadSchema.safeParse(input);
    if (!parsed.success) {
      return { status: 'invalid_request', error: { ... } };
    }

    // Chamada READ com retry exponencial + timeout 8s
    const response = await this.requestRead(parsed.data.endpoint, {
      method: 'GET',
      query: parsed.data.query,
      retries: 3,
      timeout: 8000
    });

    return response;
  }
}

Contratos por categoria já existem.

ERP, Payment, Calendar e CRM têm interfaces preparadas para adapters concretos.

Adapter desacopla o sistema externo.

A foundation permite conectar ERPs sem redesenhar o vertical; o primeiro caso concreto é PrintWayy.

Caminho para outras verticais.

Outsourcing está em construção ativa; clínica, advocacia e outros nichos seguem como roadmap.

VERTICAL PACKS
Foundation

Cada vertical
é uma pasta.

A foundation declarativa já existe: manifest, loader e template. A operação DG está em produção; o pack de outsourcing está scaffoldado e o adapter PrintWayy concluiu Fase 1 READ.

apps/verticals/
  • apps/verticals/
  • _template/ - scaffold base
  • barbearia/ em produção · DG · Rio de Janeiro
  • manifest.ts
  • flow.json
  • nlu-intents.ts
  • messages.ts
  • landing/
  • dashboard-pages/
  • outsourcing/ em construção · adapter Fase 1 READ
  • manifest.ts - snippet acima
  • flow.json
  • nlu-intents.ts
  • integrations/
  • printwayy.ts
  • skills/ - RAG vertical-específico
  • personal-trainer/ roadmap · priorização futura
  • clinica/ roadmap · Q3 2026 · Feegow
  • tatuador/ roadmap · Vision AI
  • varejo/ roadmap · P2 — P3
  • advocacia/ roadmap · P2 — P3

Exemplo da estrutura · flow.json ilustrativo

exemplo/outsourcing/flow.json
{
  "id": "outsourcing-main",
  "name": "Outsourcing — fluxo principal",
  "version": "1.0",
  "nodes": [
    {
      "id": "start",
      "type": "trigger",
      "intent": "any",
      "next": "identify_caller"
    },
    {
      "id": "identify_caller",
      "type": "lookup",
      "adapter": "printwayy",
      "method": "getCustomerByName",
      "input": "{{ message.author_name }}",
      "next": {
        "found": "main_menu",
        "not_found": "handoff_human"
      }
    },
    {
      "id": "main_menu",
      "type": "ai_response",
      "model": "claude-haiku-4-5",
      "context_window": "vertical_outsourcing"
    }
  ]
}

Exemplo da estrutura · nlu-intents.ts

exemplo/outsourcing/nlu-intents.ts
// apps/verticals/outsourcing/nlu-intents.ts

export const intents = [
  {
    id: 'consultar_fechamento',
    patterns: ['fechamento', 'fatura', 'invoice'],
    examples: [
      'fechamento de maio do cliente XPTO',
      'qual minha fatura desse mês',
      'lista os fechamentos pendentes'
    ]
  },
  {
    id: 'transferir_estoque',
    patterns: ['troquei', 'transferir', 'estoque'],
    examples: [
      'troquei toner ciano no cliente Y',
      'transfere 3 toners do estoque do Marcos pro XPTO',
      'baixa 1 cartucho do meu estoque'
    ],
    phase: 'fase-2-write' // planejado apos credenciais reais
  }
];

Cada status registra o estágio real: produção comprovada, foundation implementada, construção ativa ou visão de roadmap.

CASO TANGÍVEL
Em construção · PrintWayy adapter

O bot que opera
a empresa.

Caso-alvo em construção. A Fase 1 do adapter PrintWayy concluiu leituras: 13 endpoints READ cobertos por 30 testes. As conversas abaixo demonstram o fluxo que será validado na Fase 2, quando as credenciais reais estiverem disponíveis.

CONVERSA A · DONO · LEITURA

demonstração do fluxo planejado

09:11
L

Luna Bot

online

Dono · operação XPTO
  1. Fechamento de maio do cliente XPTO.

    09:12

  2. Fechei mês 05/2026 pro cliente XPTO. Receita bruta R$ 18.420, 3 chamados em aberto. Aqui o PDF do extrato.

    PDF fechamento-xpto-05-2026.pdf 1.4 MB

    09:12

  3. Qual minha receita total mensal projetada?

    09:13

  4. R$ 247.320 nos 12 contratos ativos. 3 contratos vencem em 30 dias.

    09:13

  5. Quais?

    09:14

  6. · XPTO Ltda — vence 15/06 · MegaCopias — vence 22/06 · Print4U — vence 28/06 Quer que eu prepare email de renovação pros 3?

    09:14

  7. Pode preparar.

    09:15

  8. Drafts gerados. Mando aqui pra você revisar antes de enviar.

    09:15

CONVERSA B · TÉCNICO · ESCRITA + PLAN-CONFIRM-APPLY

demonstração do fluxo planejado

14:30
L

Luna Bot

online

Marcos · técnico em campo
  1. Troquei toner ciano no cliente XPTO, impressora SN-ABC123.

    14:31

  2. 🔍 Identifiquei: · Cliente: XPTO Ltda (place_id 2b25…) · Impressora: Lexmark MS621dn (SN-ABC123) · Toner compatível: 56F4U00 high yield 📋 Plano de ação: · Transferir 1 toner do teu estoque → cliente XPTO · Teu estoque ciano: 4 → 3 unidades · Estoque alocado ao cliente: 0 → 1 Confirma?

    14:31

  3. Confirma.

    14:32

  4. Prévia pronta para validação da Fase 2. · audit_id planejado: aud_2826ff21 · Nenhum write executado sem credenciais reais.

    14:32

O adapter PrintWayy Fase 1 já cobre 13 endpoints READ com 30 testes.
O fluxo de write permanece planejado para Fase 2, condicionado a credenciais reais.
A tabela dedicada de audit de writes entra junto aos adapters externos quando a Fase 2 começar.

Não vai ser chatbot. Vai ser operador estruturado. O marco atual é validar PrintWayy Fase 2 com credenciais reais, sem prometer writes antes disso.

COMPARATIVO HONESTO

n8n e Luna
não competem.

Resolvem coisas diferentes. Combinam bem.

  • Decisão

    n8n

    If/then fixo

    Luna

    Tool use validado no Cockpit

  • Mudança de fluxo

    n8n

    Edição visual do grafo

    Luna

    Manifest declarativo (foundation)

  • Linguagem natural

    n8n

    Trigger via keyword

    Luna

    NLU híbrido state-aware

  • Plan-confirm-apply

    n8n

    Manual no fluxo

    Luna

    Produção no Cockpit; adapters em extensão

  • Multi-tenant

    n8n

    Workflow separado por cliente

    Luna

    Tenant isolado nativo (JWT)

  • Audit log

    n8n

    Custom

    Luna

    Cockpit ativo; adapters em construção

  • Compliance

    n8n

    Custom

    Luna

    Controles declarados por estágio

  • Onde brilha

    n8n

    Automação backend, integrações

    Luna

    Atendimento conversacional, vendas, suporte

— Combinação ideal

n8n no backend, Luna no front-WhatsApp.

Cliente que precisa de automação interna (sync entre sistemas, ETL, integrações backend) + atendimento conversacional vai usar os dois, não escolher entre.

OPERAÇÃO

Auditoria por design.
LGPD e PL 2338 por padrão.

Multi-tenant + IA + integração ERP exige transparência operacional. Os controles ativos e os próximos marcos estão declarados separadamente.

01

Security audit GO

Em produção

Auditoria recente corrigiu 14 vulnerabilidades, incluindo HMAC, timingSafeEqual, requireApiKey, CORS filtrado, rate limit e HS256 explícito.

02

Logs estruturados

Em produção

Requests HTTP e erros operacionais geram logs estruturados com contexto de tenant; telefones são mascarados onde há PII operacional.

03

Audit log de writes

Em construção

A tabela integration_writes_audit ainda é marco dos adapters externos; não é tratada como entregue na Fase 1 PrintWayy.

04

Healthchecks

Em produção

O flows-backend responde /health em produção com status saudável e versão atual do serviço.

05

Aviso de IA

Em produção

Primeira mensagem do bot identifica explicitamente "você está falando com IA da [empresa]". PL 2338 art. 11.

06

Handoff humano

Em produção

Comando "atendente" ou "humano" sempre escala. Sem fricção. PL 2338 art. 12.

07

Retention configurável

Em construção

Políticas formais de retenção e anonimização configurável por tenant seguem no marco de compliance.

Formato planejado · audit log de integração

integration_writes_audit.planned.json
{
  "audit_id": "aud_2826ff21",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_phone": "+5521987654321",
  "tool_name": "printwayy_transfer_stock_item",
  "input": {
    "stockItemId": "9ae021f3-84e3-4f4a-9ff2-4ae63c394791",
    "quantity": 1,
    "sourceCustomerPlaceId": "tech_marcos_id",
    "destCustomerPlaceId": "2b255a86-bf14-4ca5-b4cb-e7dc678eae07"
  },
  "phase": "apply",
  "confirmed_by": "+5521987654321",
  "confirmed_at": "2026-05-21T14:32:18.234Z",
  "response_status": 200,
  "latency_ms": 412,
  "request_id": "req_4f1a2b3c"
}
TRAÇÃO
Em produção · DG Barbearia

Números reais.
DG Barbearia, Rio de Janeiro.

Métricas reais do tenant DG, confirmadas em 1 de junho de 2026.

230

agendamentos

bdb_appointments

148

concluídos

status completed

237

leads capturados

fb_leads

6

assinantes ativos

bdb_subscribers

74+

dias em operação

desde março/2026

Barbearia única em Vila Isabel, Rio de Janeiro. Operação solo, contínua desde março de 2026. Bot atende, agenda, confirma, qualifica leads e mantém assinaturas recorrentes — sem intervenção humana no fluxo padrão.

PRÓXIMOS MARCOS

O que vem.

  1. concluído

    Maio 2026

    • Integration Hub foundation ✓
    • Vertical Packs foundation ✓
    • Prompt Caching
    • RAG institucional 15 docs
  2. concluído

    1 jun 2026

    • Luna Engine fases 0-4 completas
    • Tool use institucional
    • Memória cross-session
    • Security audit GO
  3. em execução

    Q3 2026

    • PrintWayy Fase 2 após credenciais
    • Writes auditados para adapters externos
    • Smoke test end-to-end com ambiente real
    • Outsourcing flow calibrado
  4. futuro

    Q4 2026

    • RAG pgvector/HNSW se volume exigir
    • Workflows assíncronos
    • Novas verticais após cliente validado
    • Multi-canal somente após WhatsApp estabilizado

Roadmap detalhado disponível para parceiros após NDA. Versão pública sincronizada com commits no monorepo.