Bonuxo: uma plataforma de fidelidade multi-tenant em produção

O que é e em que estado está

O Bonuxo é uma plataforma de fidelidade multi-tenant: pontos, selos, prêmios, roleta de prêmios, estatísticas e cartões na Apple e no Google Wallet. Tem uma API pública para sistemas de POS, integrações com e-commerce e cobrança recorrente com MercadoPago. Está em produção em bonuxo.com, com a interface em 4 idiomas.

A plataforma está em produção. O Nux, o assistente com IA do painel, está em construção: sua camada de LLM está construída e testada, mas desligada em produção. Mais abaixo há uma seção própria com o estado dele.

O problema que resolve

Um negócio que quer fidelizar clientes precisa de três coisas ao mesmo tempo: regras de recompensa configuráveis, que essa fidelidade viva na carteira do celular do cliente e que ela se conecte com o caixa onde se cobra. O Bonuxo resolve as três numa única plataforma, compartilhada por muitos negócios e com os dados de cada um separados.

Arquitetura

O backend segue Clean Architecture em 4 projetos: Domain, Application, Infrastructure e Api. Roda em .NET 8 com PostgreSQL 16 e Redis 7; os frontends são React.

O isolamento entre negócios é feito com filtros globais de consulta do EF Core em cada entidade com tenant, combinados com exclusão lógica e guardados por um teste de arquitetura. O tenant vem de um claim do JWT, e o esquema de API key para POS emite o mesmo claim, então os dois caminhos de entrada chegam ao domínio com a mesma forma.

• O Redis é usado para cache atrás de um decorator resiliente (uma queda do Redis vira um cache miss, não um erro 500), contadores de limite de taxa, um contador antifraude, um lock distribuído e sondas de saúde.
• O deploy são 9 aplicações no Coolify: backend, 6 frontends, Postgres e Redis. Se falta um segredo obrigatório, o deploy aborta. Há endpoints de liveness e readiness.

Motor de fidelidade

Há várias estratégias de fidelidade: selos, cashback, desconto progressivo, assinatura e pontos (por visita ou por valor). Todas passam por um único núcleo de acúmulo.

• Bloqueio de linha com FOR UPDATE.
• Garantia de exactly-once com uma chave econômica e um índice UNIQUE parcial.
• Um outbox e estornos tipados.
• Um job de expiração de pontos: mínimo de 30 dias, com avisos aos 30 e aos 7 dias.
• A roleta de prêmios usa um gerador aleatório criptográfico, uma barreira antifraude no Redis e uma auditoria no Postgres.

Cartões no Apple e no Google Wallet

Apple Wallet: o .pkpass é assinado como PKCS7 destacado com SHA-256. Implementa o web service de registro de dispositivos da Apple, com um push APNs por HTTP/2 depois de cada transação e um monitor de expiração do certificado.

Google Wallet: usa um JWT de salvamento assinado com RS256, atualizações do objeto por patch e uma sincronização geográfica periódica.

API para POS e e-commerce

• API keys com prefixos live e test. Só o hash SHA-256 é guardado, e o esquema de autenticação é separado do de JWT.
• Limites por chave (600 por minuto) e por IP, um Idempotency-Key opcional com retenção de 24 horas, vendas exactly-once e um teto de payload de 256 KB.
• Contrato OpenAPI 3.0.3, versão 1.3.0, com 10 paths.
• Integrações verificadas no código: Fudo (POS), TiendaNube (e-commerce) e um adaptador de MercadoPago POS, com polling e reconciliação.

Fiz um teste de carga contra a produção com uma chave sandbox em 30 de setembro de 2026: até 900 requisições por minuto, 3084 requisições e 0 erros, com p95 de 66 a 126 ms por endpoint. O teste encontrou que o limite por chave não estava sendo aplicado; corrigi isso no código.

Cobrança com MercadoPago

A cobrança recorrente usa assinaturas preapproval. A assinatura do webhook é verificada com HMAC-SHA256 em tempo constante, e cada webhook é reivindicado em duas fases de forma idempotente, tratando eventos duplicados e fora de ordem. Um serviço de reconciliação somente leitura compara as assinaturas guardadas com as do MercadoPago.

Segurança e observabilidade

• JWT de acesso de 15 minutos e refresh tokens de 7 dias guardados com hash, sem tolerância de relógio. Senhas com BCrypt e bloqueio por tenant.
• 2FA com TOTP e códigos de recuperação.
• RBAC com 4 papéis, mais permissões por membro e limites por capacidade do plano.
• Auditoria das escritas privilegiadas, sem guardar os corpos.
• Cabeçalhos de segurança com HSTS preload e CSP. AES-256-GCM para API keys e dados pessoais. Os dados pessoais são depurados antes de chegar ao Sentry.
• A configuração falha logo na inicialização se algo estiver faltando.
• Observabilidade com Sentry, com tags de tenant e de correlação, e logs estruturados com Serilog.

Servidor MCP próprio para operar o banco

Escrevi um servidor MCP próprio, em TypeScript, para operações no banco de dados. Uso em desenvolvimento e operação. Tem 5 ferramentas: escrita DML com guardas, explain, geração de scripts, DDL de uma lista permitida e aplicação de migrações com controle por checksum.

As guardas são uma barreira por ambiente, um bloqueio de produção, um token de confirmação, uma lista de bloqueio de DDL, somente DML, timeouts de statement e de lock, e rollback automático.

Nux: o assistente com IA, em construção

O Nux é o assistente do painel para o dono e a equipe. Está em construção. A camada determinística (tours guiados, ajuda contextual e um router de 23 intenções) está ativa para todos os negócios.

O agente com LLM usa tool calling com 19 ferramentas: 12 de leitura, 5 de confirmação e 2 de confirmação forte. As escritas exigem confirmação humana e respeitam as permissões do usuário, com no máximo 8 rodadas de ferramentas por turno. O provedor é intercambiável entre OpenAI e Anthropic, e há tetos de custo por plano e um registro de uso.

O que está em produção e o que não está

• Em produção: a plataforma de fidelidade, os wallets, a API de POS, a cobrança com MercadoPago e o servidor MCP.
• Em produção para todos os negócios: a camada determinística do Nux.
• Em construção: o agente com LLM do Nux, desligado em produção, e sua integração com LangGraph, LangChain, RAG e Langfuse.