EngiFlow — Documento Técnico

01 — INFRAESTRUTURA

Decisão de Stack e Hospedagem

A plataforma multi-especialidade é separada em duas zonas: Cloudflare (edge-native, sem ops de servidor) e VPS (exclusivo para o bridge WhatsApp persistente). Esse split é intencional — o VPS não carrega API, banco ou front.

☁ Cloudflare Pages

FRONTEND — REACT + TS

Dashboard interno (painel operacional)
Portal do cliente (subdomínio separado)
Deploy automático via Git
CDN global — zero configuração
Build por especialidade via feature flags

CF PAGES

⚡ Cloudflare Workers

API — TYPESCRIPT EDGE

API REST modular por especialidade
Autenticação JWT + RBAC multi-papel
Scheduled Worker: motor de vencimentos (cron diário)
Geração de PDF (certificados e laudos)
Integração nativa D1 / KV / R2
Webhook receiver para WhatsApp bridge

CF WORKERS

🟣 VPS Dedicado

WHATSAPP BRIDGE — GO

Go + whatsmeow — cliente WA Web
Processo contínuo (sessão persistente)
Recebe mensagem → POST para Worker API
Envia resposta via endpoint do Worker
SQLite local para sessão WA
VPS de 2GB RAM suficiente (~R$40/mês)

VPS — GO

🗄 Cloudflare D1

BANCO DE DADOS — SQLite MANAGED

Banco principal: todas as especialidades
Migrations com Drizzle ORM
Acesso nativo dentro do Worker
Backups automáticos gerenciados

CF D1

📦 Cloudflare R2

STORAGE — ARQUIVOS

Certificados PDF (SST)
Laudos técnicos (Elétrica)
Plantas e memoriais (Civil)
Evidências fotográficas
ARTs e documentos regulatórios
Zero custo de egresso

CF R2

💾 KV + Email

SESSÕES / CACHE / TRANSACIONAL

KV: sessões JWT, tokens de portal
KV: rate limiting por empresa
Resend: e-mails transacionais
Alertas de vencimento por e-mail

CF KV + RESEND

Por que D1 e não PostgreSQL? Para B2B multi-especialidade em escala inicial a média, o D1 elimina todo overhead de ops. Zero backups manuais, zero tuning, acesso direto no Worker. Se analytics pesado for necessário, migração via Hyperdrive sem reescrever lógica.

VPS é obrigatório apenas para WA: whatsmeow precisa de WebSocket persistente — Workers são stateless por natureza. VPS leve (~2GB RAM) resolve. Nada mais roda no VPS.

02 — STACK

Decisões Técnicas por Camada

CAMADA	TECNOLOGIA	JUSTIFICATIVA
Frontend painel interno	React + TS + Vite	Dashboard complexo com múltiplas especialidades, tabs, filtros por área e estado previsível.
Frontend portal cliente	React + TS + Vite	Subdomínio separado, auth própria, acesso a cert., laudos e status — mesma base de componentes.
API / Backend	CF Workers (TypeScript)	Edge-native, sem servidor, latência mínima, deploy automático, integração nativa com D1/KV/R2.
Banco de dados	CF D1 (SQLite)	Gerenciado, zero ops, acesso direto no Worker. Drizzle ORM para migrations tipadas.
Armazenamento	CF R2	PDFs, laudos, fotos, ARTs. URLs assinadas para acesso seguro. Zero custo de egresso.
WhatsApp Bridge	Go + whatsmeow (VPS)	Sessão WA persistente exige processo contínuo. whatsmeow é a lib Go mais estável para WA Web.
Geração de documentos	PDFLib (WASM no Worker)	Cert. SST, laudos elétricos e relatórios civis gerados diretamente no Worker, salvos no R2.
Motor de vencimentos	Scheduled Worker (cron)	Roda diariamente, varre D1 por vencimentos de todas as especialidades, dispara ações e alertas.
Autenticação	JWT + CF KV	RBAC: admin, operador, instrutor, engenheiro, cliente. Sessões em KV com expiração.
E-mail transacional	Resend	Alertas de vencimento, confirmações, envio de documentos. Integra nativamente com Workers.

03 — MÓDULOS

Estrutura de Módulos por Especialidade

A plataforma é dividida em módulo de núcleo compartilhado (CRM, financeiro, documentos, WhatsApp, painel) e módulos específicos por especialidade. Cada módulo tem suas rotas de API, tabelas no D1 e espaço no frontend.

CRM Unificado

TODAS

Empresa / cliente B2B (matriz + filiais)
Contatos por empresa e função
Origem do lead (WA, site, indicação)
Pipeline por especialidade (SST / Civil / Elet)
Histórico de interações e oportunidades
Follow-up e tarefas comerciais

Turmas e Certificados — SST

SST

Turmas in company e abertas
Tipo de treinamento vinculado à NR
Instrutor + local + vagas
Registro de presença por participante
Certificado PDF gerado automaticamente
QR code de verificação único por cert.
Validade e reciclagem registradas

Projetos e Obras — Civil

CIVIL

Ordem de serviço / projeto por cliente
Cronograma com etapas e dependências
Responsável por etapa com prazo
Registro de execução: fotos e evidências
Controle de medições aprovadas
Medição aprovada → cobrança disparada
Status de obra em tempo real

Laudos e Vistorias — Elétrica

ELÉTRICA

Abertura de vistoria com checklist técnico
Geração de laudo com template
ART vinculada ao serviço
Controle de etapas de execução
Aceite técnico → cobrança disparada
Validade do laudo monitorada (cron)
Renovação periódica programada

Vencimentos e Renovação — SST

SST

Cron diário varre todos os certificados
Radar: vencido / 7d / 30d / 60d
Alerta via WhatsApp e e-mail
Proposta automática gerada
Score de conformidade por empresa
Turma inteligente: agrupa empresas similares

Financeiro Integrado

TODAS

Proposta → contrato → cobrança por especialidade
Gatilho automático: etapa concluída → fatura
Contas a receber por área
Receita por empresa, tipo e período
Receita recorrente por renovação
Serviço realizado sem cobrança (alerta)

Cofre de Documentos

TODAS

Cert. SST, laudos elétricos, plantas civis
ARTs, memoriais, relatórios técnicos
Versão, validade, responsável por arquivo
URLs assinadas do R2 para download seguro
Disponível no portal do cliente

Painel Gerencial

TODAS

KPIs por especialidade: SST / Civil / Elétrica
Receita realizada vs. a receber por área
Vencimentos críticos (esta semana)
Pipeline ativo com valor estimado
Obras e projetos em risco de prazo
Clientes com maior risco de churn

04 — FLUXOS

Fluxos Operacionais por Especialidade

Cada fluxo representa um processo completo de ponta a ponta. Toda transição de estado gera evento rastreado no D1 com timestamp, usuário e motivo. Nenhuma mudança acontece sem rastro.

SSST — Da turma ao certificado automático

Pós-contrato: operação completa de treinamento com geração automática de certificados.

TURMACriada + instrutor alocado

→

LISTAParticipantes adicionados

→

LEMBRETEWA automático para inscritos

→

PRESENÇAInstrutor registra no dia

→

REALIZADAStatus atualizado

→

COBRANÇALiberada automaticamente

→

CERT.PDFs gerados (R2)

→

VALIDADEVencimento registrado no D1

SSST — Motor de renovação automático (cron diário)

Roda todo dia sem intervenção humana. Transforma vencimento em nova oportunidade comercial.

CRONScheduled Worker dispara

→

VARREDURAD1: certs. próximos do venc.

→

RADARVencido / 7d / 30d / 60d

→

ALERTAWA / e-mail para responsável

→

CRMOportunidade de renovação criada

→

TAREFAFollow-up no pipeline comercial

→

VENDANova proposta iniciada

CCivil — Da proposta à medição faturada

Cada etapa concluída e medição aprovada gera automaticamente o gatilho de cobrança — sem depender do financeiro mandar.

CLIENTELead / proposta

→

VISITATécnica agendada

→

CONTRATOART emitida

→

CRONOGRAMAEtapas com responsável

→

EXECUÇÃOFotos e evidências

→

MEDIÇÃOAprovada pelo gestor

→

COBRANÇAGerada automaticamente

→

ENTREGAPós-obra registrado

EElétrica — Da vistoria ao aceite técnico faturado

Aceite técnico assinado pelo cliente libera automaticamente a fatura — sem intervenção manual do financeiro.

LEADAbertura no CRM

→

VISTORIAChecklist técnico

→

LAUDOGerado + salvo R2

→

ARTEmitida e vinculada

→

EXECUÇÃOEtapas e testes

→

ACEITECliente confirma

→

FATURAGerada automaticamente

→

VALIDADELaudo monitorado

WWhatsApp — Da mensagem ao lead estruturado

Qualquer especialidade pode ter lead gerado via WhatsApp. O bridge Go processa e o Worker cria o registro correto no CRM.

WA BRIDGEMensagem recebida (Go)

→

PARSENúmero + intenção extraída

→

WORKERPOST /api/wa/inbound

→

D1Lead criado / contato atualizado

→

CLASSIFICAÇÃOSST / Civil / Elétrica

→

CRMPipeline correto ativado

→

RESPOSTABot responde via WA

05 — MODELO DE DADOS

Entidades Principais por Especialidade

Cada especialidade tem suas entidades próprias mas todas compartilham a entidade EMPRESA do CRM central. Nenhuma ação importante acontece sem registro rastreável no D1.

EMPRESA (shared)

iduuid

nome / cnpjtext

segmentotext

especialidade_ativajson[]

status_crmenum

origem_leadtext

portal_tokentext

TURMA (SST)

empresa_id→ EMPRESA

treinamento_nrtext

instrutor_id→ USUARIO

data_iniciotimestamp

statusenum

cobranca_id→ COBRANÇA

CERTIFICADO (SST)

participante_id→ PART.

r2_urltext

qr_hashtext

validade_atetimestamp

statusenum

nr_vinculadatext

PROJETO (Civil)

empresa_id→ EMPRESA

tipo_obratext

responsavel_tecnico→ USER

data_inicio / fimtimestamp

statusenum

art_id→ DOC

MEDIÇÃO (Civil)

projeto_id→ PROJETO

etapatext

valordecimal

aprovada_emtimestamp

cobranca_id→ COBR.

evidenciasjson[]

LAUDO (Elétrica)

empresa_id→ EMPRESA

tipo_laudotext

r2_urltext

qr_hashtext

validade_atetimestamp

art_id→ DOC

Rastreabilidade universal: Todas as entidades têm tabela *_events com: quem, quando, de qual estado, para qual estado, e motivo. Isso alimenta o histórico no painel, no portal do cliente e futuros relatórios.

06 — ESTADOS

Lifecycle por Especialidade

Cada serviço/processo tem estados bem definidos com transições rastreadas. O painel mostra em qual estado cada entidade está em tempo real.

SST — TURMA

📋

AGENDADA

Data, instrutor e local definidos

✅

CONFIRMADA

Lista fechada, lembretes enviados

🎓

EM ANDAMENTO

Presença aberta no dia

📄

REALIZADA

Presença fechada, cobrança liberada

🏅

CERTIFICADA

PDFs no R2, enviados ao cliente

❌

CANCELADA

Motivo registrado

CIVIL — PROJETO

📐

PROPOSTA

Escopo e orçamento definidos

📝

CONTRATO

ART emitida, início autorizado

⚙️

EM EXECUÇÃO

Etapas em andamento com resp.

📏

MEDIÇÃO

Etapa concluída, medição aprovada

💰

FATURADO

Cobrança disparada automaticamente

🏗️

ENTREGUE

Pós-obra registrado

ELÉTRICA — SERVIÇO

🔍

VISTORIA

Checklist técnico iniciado

📋

LAUDO GERADO

PDF salvo no R2

🔧

EM EXECUÇÃO

Etapas e testes em andamento

✔️

ACEITE TÉCNICO

Cliente confirma entrega

💰

FATURADO

Fatura gerada automaticamente

⏰

EM VALIDADE

Laudo monitorado via cron

07 — WHATSAPP

Bridge WhatsApp — Detalhamento Técnico

O bridge roda em VPS como processo Go contínuo. Não tem lógica de negócio — apenas recebe/envia mensagens e se comunica com a Worker API por HTTPS autenticado por HMAC.

01

whatsmeow mantém WebSocket persistente com servidores WA Web. Recebe mensagem de qualquer contato.

VPS — Go

02

Bridge extrai: número, texto, timestamp, tipo. Monta payload JSON com metadata.

Go parser

03

Bridge faz POST para /api/wa/inbound no Worker. Autenticado por HMAC secret compartilhado.

HTTPS → Worker

04

Worker busca número no D1. Novo → cria lead (origem: whatsapp). Existente → atualiza último contato.

D1 lookup

05

Worker classifica especialidade e intenção: SST (treinamento/cert.), Civil (obra/projeto), Elétrica (laudo/vistoria). Rota para pipeline correto.

Worker logic

06

Worker monta resposta e envia para /api/wa/send no bridge Go. Bridge entrega via whatsmeow.

Worker → Go → WA

07

Evento registrado no D1. Painel exibe interação. Se lead novo: alerta CRM por especialidade.

D1 event log

08 — DIFERENCIAIS

O que torna a plataforma inovadora

🔀

Fluxo automático por especialidade

O sistema detecta o tipo de serviço (SST / Civil / Elétrica) e abre o checklist, as etapas e os documentos corretos para aquela especialidade. Não é adaptação manual — é lógica nativa.

⚡

Financeiro por gatilho operacional

Medição aprovada → cobrança criada. Turma realizada → fatura liberada. Aceite técnico → conta a receber. O financeiro reage à operação, não o contrário.

🔄

Motor de renovação multi-especialidade

Cron único que monitora: cert. SST (por NR), laudos elétricos (por validade) e inspeções civis (por contrato). Qualquer vencimento gera alerta, oportunidade e tarefa automaticamente.

🔍

QR code de verificação em documentos

Cert. SST e laudos elétricos têm QR code único. Qualquer auditoria escaneia e confirma autenticidade. Hash de verificação no D1 — não depende de terceiro.

📊

Radar de conformidade SST por empresa

Score de 0 a 100 por empresa cliente mostrando colaboradores treinados, vencidos e pendentes por função e filial. O cliente vê no portal — cria urgência de compra genuína.

🌐

Portal do cliente por especialidade

O cliente acessa: cert. SST, laudos elétricos, status de obra civil, documentos, vencimentos e pendências — sem ligar. Reduz atendimento manual e aumenta percepção de valor.