01 — Infraestrutura
Decisão de Stack e Hospedagem
A plataforma é dividida em duas zonas de infraestrutura: a zona Cloudflare (edge-native, sem servidor
para gerenciar) e a zona VPS (necessária apenas para o bridge WhatsApp via Go + whatsmeow). Essa
separação é intencional: o VPS não precisa carregar o peso da API ou do banco de dados.
⚡
Cloudflare Pages
FRONTEND
- React + TypeScript (Vite)
- Deploy automático via Git
- CDN global — zero latência
- Preview environments por branch
- Portal cliente separado (subdomínio)
CF PAGES
🔧
Cloudflare Workers
API + BACKEND
- TypeScript — runtime edge (Bun-compatible)
- API REST ou RPC por módulo
- Autenticação JWT + RBAC
- Validação de entrada tipada
- Scheduled Workers para motor de vencimentos
- Integração com D1, KV, R2
CF WORKERS
🟣
VPS Dedicado
WHATSAPP BRIDGE
- Go + whatsmeow (cliente WA oficial)
- Recebe e envia mensagens via WA Web
- Processa mensagens → chama Worker API
- Mantém sessão persistente (SQLite local)
- Pequeno VPS é suficiente (2GB RAM)
VPS — GO
🗄️
Cloudflare D1
BANCO DE DADOS PRINCIPAL
- SQLite managed pelo Cloudflare
- Acesso nativo dentro do Worker
- Suporte a migrations versionadas
- Backups automáticos
- Suficiente para escala B2B SST
CF D1
📦
Cloudflare R2
ARMAZENAMENTO DE ARQUIVOS
- Certificados PDF gerados
- Listas de presença escaneadas
- Evidências fotográficas
- Documentos técnicos (PGR, etc.)
- Zero custo de egresso
CF R2
💾
Cloudflare KV
CACHE + SESSÕES
- Sessões de autenticação
- Cache de dados frequentes
- Rate limiting por empresa
- Tokens de convite/portal
CF KV
Por que não PostgreSQL no VPS? Para esse domínio (B2B SST, dezenas a centenas de
empresas clientes), o D1 no Cloudflare elimina toda a gestão de banco de dados — sem backups manuais,
sem tuning, sem custo fixo de infra. Se no futuro a escala exigir queries analíticas pesadas, a migração
para PostgreSQL via Hyperdrive é direta sem reescrever lógica de negócio.
Exceção — VPS obrigatório: O whatsmeow (Go) precisa manter uma sessão WebSocket
persistente com os servidores do WhatsApp. Workers Cloudflare são stateless por natureza, então o bridge
deve rodar em processo contínuo. Um VPS de R$30–50/mês resolve isso.
02 — Stack
Tabela de Decisões Técnicas
| CAMADA |
TECNOLOGIA |
JUSTIFICATIVA |
| Frontend interno (painel) |
React + TypeScript + Vite |
Tipagem forte, componentização por módulo, estado previsível. Dashboard complexo
com múltiplos tabs e fluxos. |
| Frontend externo (portal cliente) |
React + TypeScript + Vite |
Subdomínio separado, mesma base de componentes, autenticação própria. Cliente
acessa sem acessar o painel interno. |
| API / Backend |
Cloudflare Workers (TypeScript) |
Edge-native, sem servidor para gerenciar, latência ultra-baixa, deployment
automático, integração nativa com D1/KV/R2. |
| Banco de dados |
Cloudflare D1 (SQLite) |
Gerenciado, zero ops, acesso nativo no Worker, suficiente para o volume B2B de
SST. Migrations com Drizzle ORM. |
| Armazenamento |
Cloudflare R2 |
Certificados PDF, documentos, evidências. Zero custo de egresso, URLs assinadas
para acesso seguro. |
| WhatsApp Bridge |
Go + whatsmeow (VPS) |
whatsmeow é o cliente Go mais estável para WA Web. Conexão persistente exige
processo contínuo — VPS de baixo custo. |
| Geração de certificados |
Worker + PDFLib (WASM) |
Geração de PDF diretamente no Worker usando template, sem dependência externa.
Salva no R2 e retorna URL assinada. |
| Motor de vencimentos |
Scheduled Worker (cron) |
Worker agendado roda diariamente, varre vencimentos, dispara ações comerciais e
envia alertas via WhatsApp ou e-mail. |
| E-mail transacional |
Resend / Cloudflare Email |
Envio de confirmações, alertas e documentos por e-mail. Integra nativamente com
Workers. |
| Autenticação |
JWT + Cloudflare KV |
Tokens JWT verificados no Worker. KV guarda sessões ativas. RBAC por papel
(admin, operador, instrutor, cliente). |
03 — Módulos
Estrutura de Módulos da Plataforma
A plataforma é organizada em módulos funcionais com fronteiras claras. Cada módulo tem suas rotas de API,
suas tabelas no D1 e seu espaço no frontend. Isso permite evoluir um módulo sem quebrar os outros.
CRM Comercial
- Empresas clientes (B2B, multi-filial)
- Contatos por empresa (RH, SST, diretoria)
- Pipeline de propostas
- Status: lead → proposta → contrato → ativo
- Histórico de interações
- Origem do lead (WhatsApp, indicação, site)
- Follow-up agendado
Gestão de Turmas
- Criação de turma (in company ou aberta)
- Tipo de treinamento vinculado à NR
- Local / modalidade (presencial, online)
- Instrutor responsável
- Limite de vagas e inscritos
- Status: agendada → confirmada → realizada → cancelada
- Conflito de agenda de instrutor
Participantes e Presença
- Lista de participantes por turma
- Colaborador vinculado à empresa
- Registro de presença (presente/ausente/parcial)
- Função / cargo do colaborador
- Histórico de treinamentos por pessoa
- Dados para emissão do certificado
Certificados
- Geração automática após turma realizada
- Template configurável por tipo de treinamento
- PDF salvo no R2 com URL única
- Reenvio sob demanda
- Data de emissão e validade registradas
- Disponível no portal do cliente
Vencimentos e Renovação
- Motor automático: varre D1 todo dia (cron)
- Radar: vencido / 7d / 30d / 60d
- Alerta automático via WhatsApp / e-mail
- Abertura de proposta automática
- Visão por empresa, unidade e colaborador
- Campanha de reciclagem ativável
Financeiro
- Proposta → contrato → cobrança
- Status de pagamento por turma
- Contas a receber com vencimento
- Receita por empresa / tipo / período
- Receita recorrente por renovação
- Turmas realizadas sem cobrança (alerta)
Portal do Cliente
- Login separado por empresa cliente
- Visualização de treinamentos realizados
- Download de certificados
- Painel de vencimentos da empresa
- Solicitação de nova turma
- Upload de lista de colaboradores
Painel Gerencial
- KPIs do mês: turmas, alunos, certificados
- Receita realizada vs. a receber
- Vencimentos críticos (esta semana)
- Pipeline comercial ativo
- Turmas sem pagamento confirmado
- Empresas com maior risco de churn
04 — Fluxos
Fluxos Operacionais Principais
Cada fluxo representa um processo completo de ponta a ponta, desde a origem até o evento de negócio
final. Todos os fluxos deixam rastro estruturado no banco de dados e alimentam o painel gerencial.
1Fluxo Comercial — Da prospecção ao contrato
O comercial começa com um lead e termina com uma turma agendada e contrato assinado.
INÍCIOLead capturado
(WA, site,
indicação)
CRMEmpresa criada
+ contato
vinculado
PROPOSTAProposta gerada
+
treinamentos selecionados
APROVAÇÃOCliente aprova
proposta
CONTRATOContrato gerado
+
cobrança criada
FIMTurma agendada
Operação
iniciada
2Fluxo de Turma — Da agenda ao certificado
Após o contrato, a operação de treinamento começa. O certificado é gerado
automaticamente ao final.
TURMATurma criada
+ instrutor
alocado
LISTAParticipantes
adicionados
CONFIRMAÇÃOWA envia lembrete
aos
inscritos
PRESENÇAInstrutor
registra
presença no dia
TURMA OKStatus: realizada
Cobrança
liberada
AUTOCertificados
gerados (PDF/R2)
3Fluxo de Renovação — Motor automático de recorrência
O coração da recorrência. Roda diariamente via Scheduled Worker, transforma vencimento
em oportunidade comercial.
CRON / DIAWorker verifica
todos
vencimentos
CLASSIFICAÇÃORadar: crítico
7d /
30d / 60d
ALERTAWA/e-mail
para responsável
CRMOportunidade de
renovação
criada
COMERCIALTarefa no pipeline
para
follow-up
VENDANova proposta
iniciada
4Fluxo WhatsApp — Da mensagem ao lead estruturado
Mensagem recebida no WhatsApp vira lead ou atualiza registro existente no CRM, tudo
automaticamente.
WA BRIDGEMensagem recebida
Go +
whatsmeow
PARSENúmero extraído
Intenção
detectada
WORKER APIPOST /wa/event
evento
processado
D1Lead criado ou
contato
atualizado
CRMPipeline movido
Alerta ao
comercial
RESPOSTABot responde via
WA
automaticamente
5Fluxo Portal do Cliente — Self-service da empresa contratante
O responsável de SST da empresa cliente acessa o portal sem precisar ligar ou enviar
WhatsApp.
LOGINAcesso via link
dedicado
DASHBOARDVisão geral
da
conformidade
DOCUMENTOSDownload
de
certificados PDF
VENCIMENTOSVer o que
está
vencendo
SOLICITAÇÃOPedir nova turma
ou
reciclagem
CRMSolicitação vira
oportunidade
interna
05 — Dados
Principais Entidades do Banco de Dados
Cada entidade representa um objeto de negócio com estado, histórico e relacionamentos. Nenhuma ação
importante acontece sem deixar rastro estruturado no D1.
EMPRESA
iduuid
nometext
cnpjtext
segmentotext
statusenum
origem_leadtext
portal_tokentext
created_attimestamp
TREINAMENTO
iduuid
nometext
nr_vinculadatext
carga_horariaint
validade_mesesint
template_cert_iduuid
modalidadeenum
TURMA
iduuid
treinamento_id→
TREINAMENTO
empresa_id→
EMPRESA
instrutor_id→
USUARIO
data_iniciotimestamp
localtext
statusenum
cobranca_id→
COBRANÇA
PARTICIPANTE
iduuid
turma_id→ TURMA
colaborador_id→
COLABORADOR
presencaenum
certificado_id→
CERT.
data_emissaotimestamp
data_vencimentotimestamp
CERTIFICADO
iduuid
participante_id→
PART.
r2_urltext
hash_verificacaotext
validade_atetimestamp
statusenum
enviado_emtimestamp
COBRANÇA
iduuid
empresa_id→
EMPRESA
turma_id→ TURMA
valordecimal
statusenum
vencimentotimestamp
pago_emtimestamp
06 — Estados
Lifecycle de uma Turma
Cada turma passa por estados bem definidos. Toda transição de estado é registrada com timestamp e usuário
responsável. Nenhuma mudança acontece sem rastro.
📋
AGENDADA
Turma criada, data definida, instrutor alocado
✅
CONFIRMADA
Lista fechada, lembretes enviados
🎓
EM ANDAMENTO
Dia do treinamento, presença aberta
📄
REALIZADA
Presença fechada, cobrança liberada
🏅
CERTIFICADA
PDFs gerados, enviados ao cliente
❌
CANCELADA
Motivo registrado, reagendamento sugerido
Rastreabilidade total: Cada mudança de estado gera um registro na tabela turma_events
com: quem mudou, quando mudou, de qual estado para qual estado, e motivo opcional. Isso alimenta o
histórico no painel gerencial e no portal do cliente.
07 — WhatsApp
Integração WhatsApp — Detalhamento Técnico
A integração usa Go + whatsmeow rodando em VPS como processo contínuo. O bridge não tem lógica de negócio
— ele apenas recebe/envia mensagens e se comunica com a Worker API por HTTP.
01
whatsmeow (Go) mantém conexão WebSocket persistente com servidores WhatsApp
Web. Recebe mensagem de qualquer contato.
VPS — Go
02
Bridge extrai: número do remetente, texto, timestamp, tipo de mensagem
(texto/áudio/imagem). Monta payload JSON.
Go parser
03
Bridge faz POST para endpoint /api/wa/inbound no Cloudflare Worker. Autenticado
por HMAC secret compartilhado.
HTTPS → Worker
04
Worker verifica se número existe no D1. Se não existe: cria lead novo (origem:
whatsapp). Se existe: atualiza último contato e verifica intenção.
D1 lookup
05
Worker classifica intenção: solicitar treinamento / pedir certificado / agendar
turma / falar com humano. Chama resposta adequada.
Worker logic
06
Worker monta resposta e envia para endpoint /api/wa/send no bridge Go (via
HTTP). Bridge entrega mensagem via whatsmeow.
Worker → Go → WA
07
Evento registrado no D1. Painel gerencial exibe interação. Se lead novo: alerta
no CRM para follow-up comercial.
D1 event log
Fluxo de atendimento humano: Se o bot classifica que o usuário precisa de atendimento
humano, o Worker muda o status da conversa para aguardando_humano
e aparece na fila de atendimento no painel. O operador responde diretamente pelo painel, que envia via
endpoint do bridge Go.
08 — Diferencial
O Que Torna Essa Plataforma Inovadora
Além de integrar tudo em um fluxo único, existem funcionalidades que não existem em soluções genéricas do
mercado.
Radar de Conformidade por Empresa
- Mapa visual de conformidade de cada cliente
- % de colaboradores treinados por função
- Quais filiais estão críticas
- Score de conformidade (0 a 100)
- O cliente vê isso no portal — cria urgência
Motor de Renovação Automático
- Nenhum vencimento passa despercebido
- Gera oportunidade comercial automaticamente
- WhatsApp proativo para o cliente
- Transforma operação reativa em proativa
- Recorrência vira receita previsível
Turma Inteligente (sugestão)
- Sistema detecta: empresa A precisa de NR-10
- Empresa B (mesma cidade) também precisa
- Sugere unir em turma aberta
- Reduz custo, fecha turma mais rápido
- Aumenta margem do treinador
Portal Self-Service do Cliente
- Empresa acessa histórico sem ligar
- Baixa certificado sem pedido manual
- Vê o que está vencendo sozinha
- Reduz atendimento manual em 60%+
- Gera percepção de valor premium
Certificado com QR Code de Verificação
- PDF com QR code único por certificado
- Qualquer empresa fiscalizadora escaneia
- Página pública confirma autenticidade
- Hash de verificação no banco
- Diferencial de credibilidade forte
Painel do Dono (visão total)
- O que precisa de ação hoje
- Dinheiro parado (realizado, não cobrado)
- Quem está em risco de churn
- Receita recorrente projetada
- Gargalos operacionais visíveis