Plataforma de Orquestração

O Whatsbi não é apenas um SaaS; é um projeto mantido por uma Arquitetura Agêntica Multi-Especialista. Esta camada de inteligência (localizada no diretório .agent/) coordena a manutenção evolutiva do sistema.

0. Design System: Tech-Data Brutalism (v3.0)

O Whatsbi utiliza a linguagem visual Tech-Data Brutalism. Substituímos arredondamentos genéricos e paletas saturadas por uma estética "High-End Engineering" focada em geometria pura e tipografia técnica.

1. Visão Geral do Produto

O Whatsbi é uma plataforma SaaS middleware que conecta empresas à API Oficial do WhatsApp (Meta Cloud API). Diferente de ferramentas de "disparo pirata", o Whatsbi opera em total conformidade com as políticas da Meta e LGPD.

2. Arquitetura Técnica

O sistema foi construído sobre uma arquitetura MVC (Model-View-Controller) em PHP "Vanilla" (Moderno, sem frameworks pesados), priorizando performance bruta e controle total sobre o ciclo de vida da requisição.

Stack Tecnológico

• Backend: PHP 8.2+ (PDO, Streams, GD)
• Frontend: HTML5, Vanilla JS (Fetch API), TailwindCSS (CDN/Local), Lucide Icons.
• Banco de Dados: MySQL/MariaDB (InnoDB, UTF8mb4).
• Infraestrutura: Apache (.htaccess Rewrite Rules).

Estrutura de Diretórios Completa (Full Tree)

/home/usuario/
├── app/
│   ├── config/                 # Configurações globais (Stripe, Meta, DB)
│   ├── controllers/            # Controladores MVC
│   │   ├── AuditController.php
│   │   ├── AuthController.php
│   │   ├── AutomationsController.php
│   │   ├── CampaignsController.php
│   │   ├── ContactsController.php
│   │   ├── DashboardController.php
│   │   ├── HealthController.php
│   │   ├── HomeController.php
│   │   ├── MetaController.php
│   │   ├── MetaSettingsController.php
│   │   ├── PlatformController.php
│   │   ├── PlatformFinanceController.php
│   │   ├── PlatformPlansController.php
│   │   ├── ProfileController.php
│   │   ├── SubscriptionController.php
│   │   ├── TeamController.php
│   │   ├── TemplatesController.php
│   │   └── WebhookController.php
│   ├── helpers/                # Middlewares (CompanyGuard, Auth)
│   ├── models/                 # Modelos de Dados
│   │   ├── Automation.php
│   │   ├── Campaign.php
│   │   ├── CompanySubscription.php
│   │   ├── Contact.php
│   │   ├── MessageTemplate.php
│   │   ├── Plan.php
│   │   ├── SystemSetting.php
│   │   └── User.php
│   ├── services/               # Serviços de Domínio (Meta, Stripe, Automation)
│   ├── views/                  # Camada de Apresentação
│   │   ├── automations/        # Flow Builder & Node Editor
│   │   │   ├── js/             # Lógica Modulada (state, nodes, connections, etc.)
│   │   │   └── partials/       # Partials do Workspace (canvas, inspector)
│   │   └── inbox/              # Atendimento Centralizado
│   │       └── partials/       # Componentes do Inbox (sidebar, chat)
│   └── webhooks/               # Entrypoints para Webhooks
│
├── app.whatsbi.com/            # Subdomínio de App (Router)
│   └── index.php
│
├── doc.whatsbi.com/            # Documentação
│   └── index.html
│
└── public_html/                # Webroot Pública
    ├── .htaccess
    └── index.php

Estrutura de Diretórios Atualizada (Resumo)

/home/usuario/
├── app/
│   ├── config/                 # stripe.php, meta.php
│   ├── controllers/            # AutomationsController, SubscriptionController, PlatformController, DashboardController...
│   ├── services/               # AutomationService, StripeService, MetaService, AuditService
│   ├── helpers/                # CompanyGuard, AuthMiddleware
│   ├── models/                 # CompanySubscription, Plan
│   └── webhooks/               # stripe.php, whatsapp.php
│
├── public_html/                # Domínio Principal (LP + Docs Legais)
│   ├── router.php              # Central Router (New!)
│   ├── index.php               # Front Controller Wrapper
│   └── .htaccess               # Rewrites to router.php
│
└── app.whatsbi.com/            # Subdomínio (Sistema)
    ├── .agent/                 # Brain & Artifacts
    └── views/                  # Layouts (header/footer), Platform, etc.

🔒 Segurança & Middleware

2.1 Execução em VPS (HestiaCP Production Environment)

O Whatsbi foi adaptado para funcionamento em servidores VPS com HestiaCP + Nginx + PHP-FPM. Diferente de hospedagens compartilhadas (cPanel), o Hestia aplica isolamento de diretórios via open_basedir, impedindo acesso a arquivos fora da raiz pública.

Hierarquia Real de Produção (Hestia)

/home/Whatsbi/
│
├── app/                        # CÓDIGO PRIVADO
│   ├── config/
│   ├── controllers/
│   ├── models/
│   ├── services/
│   ├── helpers/
│   ├── validators/
│   ├── webhooks/
│   ├── worker.php
│   └── storage/logs/
│
├── web/
│   └── app.whatsbi.com/
│       ├── public_html/
│       │   ├── index.php
│       │   ├── .htaccess
│       │   └── assets/
│       │
│       └── logs/
│
└── tmp/

Front Controller

define('BASE_PATH', realpath(__DIR__ . '/../../../../app'));
require BASE_PATH . '/helpers/autoload.php';

PHP-FPM obrigatório

php_admin_value[open_basedir] =
/home/%user%/web/%domain%/public_html:
/home/%user%/app:
/home/%user%/tmp:
/tmp

Worker

/usr/bin/php /home/Whatsbi/app/worker.php

Cron Oficial

* * * * * /usr/bin/php /home/Whatsbi/app/worker.php >> /home/Whatsbi/tmp/worker.log 2>&1

Logs

tail -f /home/Whatsbi/tmp/worker.log

Limpar fila antiga de erro

postsuper -d ALL
systemctl restart postfix

Recuperação

v-rebuild-user Whatsbi
systemctl restart nginx
systemctl restart php*-fpm

Configuração de E-mail Interno (SMTP via HestiaCP)

Como a aplicação roda na mesma VPS que o servidor de e-mail (Postfix), a comunicação SMTP deve ser feita localmente para evitar bloqueios de firewall e erros de certificado SSL rigorosos do PHP.

$mail->Host = '127.0.0.1';
$mail->Port = 587; // ou 25

// BYPASS DE CERTIFICADO SSL (Local/VPS)
$mail->SMTPOptions = array(
    'ssl' => array(
        'verify_peer' => false,
        'verify_peer_name' => false,
        'allow_self_signed' => true
    )
);

3. SaaS Core & Billing

4. Integração Meta (Zero Trust)

4.1 Orquestração AI (.agents)

4. Funcionalidades & Módulos

Visão consolidada dos principais módulos operacionais da plataforma Whatsbi.

5. Compliance LGPD & Perfil

O Whatsbi leva a proteção de dados a sério, oferecendo ferramentas nativas para atender à Lei Geral de Proteção de Dados (LGPD).

6. Módulo de Templates

Implementação completa da gestão de templates conforme exigências de Compliance da Meta. O módulo foi desenhado para evitar rejeições e facilitar a experiência do usuário.

7. Módulo de Campanhas

Sistema robusto de disparo em massa projetado para alta performance e segurança. Utiliza uma arquitetura de Staging -> Worker para garantir que envios grandes não travem a interface.

7.1 Módulo de Automações (Flow Builder)

O Motor de Automação Visual permite construir trilhas de atendimento e funis orgânicos. A interface é baseada em Canvas Node-Editor.

7.2 Live Chat Ecosystem: Mapeamento de Recursos

A central de atendimento do Whatsbi é um ecossistema integrado que permite a gestão fluída de conversas e a colaboração entre times. Recentemente refatorado para uma Arquitetura de Partials, permitindo atualizações modulares na Sidebar, Chat e Perfil sem interferência entre componentes.

0 3 * * * /usr/bin/php /home/Whatsbi/web/app.whatsbi.com/app/cron_ephemeral.php

A interface de atendimento (Inbox) foi aprimorada com um sistema de categorização dinâmica que permite organizar leads sem sair da conversa ativa.

7.4 Inbox: Filtros & Visibilidade Segregada

A barra lateral do Inbox agora conta com um sistema de filtros precisos para evitar a confusão entre a visão global da empresa e a fila de entrada operacional.

7.5 Inbox: Encaminhamento de Mídia

O Whatsbi disponibiliza um endpoint público para integração com sistemas externos (ERP, N8N, Make, Python scripts).

POST https://app.whatsbi.com/api/v1/trigger?id={AUTOMATION_ID}

{
  "phone": "5511999999999",
  "variables": ["Argumento 1", "Argumento 2"]
}

8. Dashboard & Métricas Pró-Ativas

O painel principal do Whatsbi (Dashboard) foi revitalizado matematicamente, abandonando gráficos estáticos em favor de visualizações e cálculos renderizados 100% via servidor e SVG.

8. Saúde da Operação (Quality Assurance)

Dashboard dedicado à monitoria técnica da qualidade da linha e entregabilidade. Fundamental para evitar bloqueios da Meta.

10.1 Mensagens Efémeras & Limpeza Automática

Para garantir a privacidade e otimizar o armazenamento do servidor, o Whatsbi utiliza um sistema de Mensagens Efémeras para as salas de chat internas (Internal Rooms).

0 3 * * * /usr/bin/php /home/Whatsbi/web/app.whatsbi.com/app/cron_ephemeral.php

11. Auditoria & Blindagem Jurídica

O Whatsbi garante rastreabilidade total através de Snapshots Imutáveis. Diferente de outros sistemas, não confiamos no estado atual do banco, mas sim na "foto" do momento do envio.

10. Modo Híbrido (Coexistência)

11. Platform Administration (Super Admin Isolado)

Ambiente de alta segurança configurado no subdomínio admin.whatsbi.com para gestão do ecossistema.

• ✅ Global Dashboard & System Status: KPIs de MRR, Total de Empresas, Volume de Mensagens, monitoramento da saúde do servidor e filas em tempo real.
• ✅ Tenant Management: Listagem e edição de todos os clientes (Tenants), configuração de acesso, data de expiração, status do plano, e gestão detalhada da empresa.
• ✅ Emergency Actions: Autenticação forçada (SSO bypass via "Imitate User") e capacidade de Bloquear/Desbloquear acesso de empresas instantaneamente e conceder Trials manuais.
• ✅ Planos & Pricing Override (Platform Plans): Criação e configuração dinâmica de faixas de cobrança, capacidade de forçar planos ou cancelar assinaturas arbitrariamente via UI.
• ✅ Módulo Financeiro & Integração Connect: Gestão segura de fluxos do Stripe (Connect), com visualização de transações globais e relatórios gerenciais consolidados.

11.1. Advanced Analytics & Reports

• ✅ Matemática de Funil Cascata: O Dashboard de analytics exibe KPIs ao vivo conectando a rota Webhook através de injeção de `context_message_id`. Isso corrige falhas onde envios Delivered e Read não conversavam entre o servidor da Meta e a View.
• ✅ Precisão de Transações em Tempo Real: Estimativa de custo de disparo nativamente formatado em 4 casas decimais.
• ✅ Contact Sync Audit (LGPD): Registros completos e auditáveis de importação de contatos (.CSV), validações de números que não existem, normalização de DDI (E164) e remoção de duplicatas (Silent Merge).

12. Governança & Multi-Workspace

Arquitetura multi-tenant avançada que permite um único usuário transitar entre múltiplas empresas (Workspaces) usando uma única conta, garantindo segurança na troca de sessão sem necessidade de re-autenticação.

13. Banco de Dados

-- Core
users, companies (rate_limit_per_second as DECIMAL 10,4)
user_company (role: admin, operator, viewer)
password_resets (email, token, created_at) -- Flow de recuperação de senha

-- CRM
contacts (id, phone_e164, consent, blocked)
contact_imports (id, status, total_rows)

-- Meta Engine
meta_integrations (access_token, status, created_at [Warm-up Source])
wabas (id [Internal PK], waba_id [Meta External ID], name, currency) -- NOTE: Separation of Internal ID vs Meta Graph ID
whatsapp_phone_numbers (phone_id, quality_rating)

-- Mensageria & Templates
message_templates (id, name, status, components, rejection_reason)
inbound_messages (wa_id, body, received_at)
outbound_messages (meta_id, status, sent_at)

-- Campanhas
plans (max_users, rate_limit_per_second as DECIMAL 10,4)
campaigns (id, status, scheduled_at, sent_count, total_contacts, last_error)
campaign_messages (campaign_id, contact_id, status, meta_message_id)

-- Auditoria & Compliance (Blindagem)
message_audit_logs (snapshot imutável: template + variáveis + consentimento)
message_status_logs (histórico de entrega: sent -> delivered -> read)
contact_optout_logs (prova jurídica de bloqueio: source + reason)

-- System (Super Admin)
system_settings (key_name, value, updated_at) -- Stripe Keys, Global Configs

14. Roadmap (Status)