Infraestrutura Técnica

Versão 1.1 — Atualizado em 14/03/2026

Documentação completa da arquitetura de backend do ecossistema Grupo CSV. Descreve todos os microserviços (Workers), banco de dados, armazenamento, rotas de API, fluxos de autenticação e tarefas agendadas que sustentam o Hub e seus portais.

Este documento serve como referência técnica definitiva para desenvolvedores, agentes de IA e qualquer pessoa que precise compreender o funcionamento interno do sistema.

Nota sobre segurança: Este documento descreve a arquitetura e o funcionamento dos componentes. Informações sensíveis (chaves de API, tokens, senhas) não estão incluídas. O proprietário mantém uma estrutura de gerenciamento de segredos própria, que pode ser consultada sob seu consentimento expresso.

1. Visão Geral da Arquitetura

O backend do Hub CSV é construído sobre a plataforma Cloudflare, utilizando uma arquitetura de microserviços implementada com Cloudflare Workers. Cada worker é um serviço independente, com responsabilidade única, que se comunica com os demais através do API Gateway.

┌─────────────────────────────────────────────────────────────────┐ │ CLIENTE (Navegador) │ │ │ │ hub.grupocsv.com ─── GitHub Pages (Frontend) │ │ ├── VitePress (Infra, Compass, Signal) │ │ ├── Portais HTML (Unimed, ICDS, AxiaCare, Thera, MedValor) │ │ ├── Admin (/admin/) │ │ ├── Deck (/deck/) │ │ └── Compliance (/compliance/) │ └──────────────────────────┬──────────────────────────────────────┘ │ Chamadas de API ▼ ┌─────────────────────────────────────────────────────────────────┐ │ API GATEWAY (csv-gateway) │ │ api.grupocsv.com — v1.6.0 │ │ │ │ Autenticação ─── Roteamento ─── Logging ─── CORS │ └──────┬──────┬──────┬──────┬──────┬──────┬──────┬───────────────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ ▼ ▼ ▼ ▼ ┌──────┐┌──────┐┌──────┐┌──────┐┌──────┐┌──────┐┌──────────┐ │ auth ││ data ││ ai ││ cron ││email ││webhk ││propostas │ │v3.0.0││ ││ ││v2.0 ││ ││ ││ │ └──┬───┘└──┬───┘└──────┘└──┬───┘└──────┘└──────┘└────┬─────┘ │ │ │ │ ▼ ▼ ▼ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ ARMAZENAMENTO │ │ │ │ D1 Database (csv-hub) KV Store (csv-config) │ │ ├── users ├── Senhas de portais │ │ ├── user_tenants └── Configurações dinâmicas │ │ ├── pending_requests │ │ ├── auth_sessions R2 Storage (csv-propostas) │ │ ├── access_logs └── Propostas HTML/PDF │ │ ├── api_logs │ │ └── email_logs │ └─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐ │ SERVICO INDEPENDENTE (fora do gateway) │ │ │ │ csv-mail v1.0.0 ─── mail-api.grupocsv.com │ │ Autenticação própria (Bearer API Key) │ │ Bindings: D1 (csv-hub), Resend │ └─────────────────────────────────────────────────────────────────┘

Repositórios de Código

Repositório	Conteúdo	Deploy
`grupocsv/hub`	Frontend completo: VitePress, portais HTML, compliance, admin, deck	GitHub Pages
`grupocsv/backend`	Workers Cloudflare: csv-auth, csv-gateway, csv-data, csv-email, csv-mail, csv-ai, csv-cron, csv-propostas, csv-webhook, thera-contact	Cloudflare Workers

2. API Gateway (`csv-gateway`)

O csv-gateway é o ponto de entrada para todas as chamadas de API, acessível em api.grupocsv.com. Recebe a requisição, valida a autenticação quando necessário, registra o log no D1 e encaminha (proxy) para o worker de destino.

Mapa de Rotas

Prefixo	Worker de Destino	Acesso	Descrição
`/auth`	csv-auth	Público	Login, verificação de token, solicitação de acesso, painel admin
`/thera/contact`	thera-contact	Público	Formulário de contato do site Thera
`/webhook`	csv-webhook	Público	Recebe webhooks de serviços externos
`/data`	csv-data	Protegido	Consultas ao D1 e KV
`/ai`	csv-ai	Protegido	Proxy para Cloudflare AI Gateway
`/cron`	csv-cron	Protegido	Disparo manual de tarefas agendadas
`/email`	csv-email	Protegido	Envio de e-mails transacionais via Resend
`/axiacare/propostas`	csv-propostas	Protegido	Geração de propostas comerciais

Nota: O worker csv-mail opera fora do gateway, acessível diretamente em mail-api.grupocsv.com com autenticação própria via Bearer token (API key dedicada). Não consta na tabela acima por não utilizar o roteamento do csv-gateway.

Autenticação do Gateway

Rotas marcadas como Protegido exigem uma API Key, enviada no header X-API-Key ou como parâmetro de query ?key=. Rotas públicas são acessíveis sem autenticação. Todas as requisições são registradas na tabela api_logs do D1 com worker, método, path, status e tempo de resposta.

3. Workers de Serviço

Cada worker é um microserviço independente com responsabilidade única. Todos rodam na edge da Cloudflare, garantindo latência mínima globalmente.

csv-authv3.0.0

Serviço central de autenticação e controle de acesso. Gerencia login, tokens de sessão, solicitações de acesso, aprovação de usuários e o painel administrativo.

Bindings: D1 (csv-hub), Secret (RESEND_API_KEY), Secret (GITHUB_PAT)

POST /login — Valida credenciais e retorna token de sessão (24h)
GET /verify — Valida um token de sessão existente
POST /logout — Encerra uma sessão ativa
POST /request-access — Cria solicitação de acesso para portais de parceiros
GET /admin/stats — Estatísticas do painel (usuários, solicitações, links)
GET /admin/pending-requests — Lista solicitações pendentes
POST /admin/approve — Aprova solicitação e cria usuário
POST /admin/reject — Rejeita solicitação de acesso
GET /admin/users — Lista usuários aprovados com seus tenants
POST /admin/revoke — Revoga acesso de um usuário a um tenant
GET /admin/logs — Log de acessos externos (com JOIN de nome)
GET /admin/passwords — Senhas dos portais de empresas (do KV)
POST /admin/update-password — Atualiza senha de portal de empresa
POST /admin/revoke-public-link — Revoga link público (commit no GitHub)
POST /admin/restore-public-link — Restaura link público revogado
POST /admin/cleanup-sessions — Remove sessões expiradas
POST /deck/reset-pin — Envia PIN temporário por e-mail

csv-cronv2.0

Executa tarefas agendadas via Cron Triggers da Cloudflare. Gera o relatório diário, monitora a saúde dos workers e realiza limpeza periódica do banco.

Bindings: D1 (csv-hub), Secret (RESEND_API_KEY)

0 12 * * *

Relatório Diário — 09:00 BRT. Coleta métricas de API, autenticação, dados TEA e propostas. Envia por e-mail.

*/30 * * * *

Health Check — A cada 30 min. Verifica status de todos os workers. Envia alerta se algum estiver fora do ar.

0 6 * * SUN

Limpeza Semanal — Domingo 03:00 BRT. Remove sessões expiradas e logs antigos (> 90 dias).

csv-dataFase 3

Interface de consulta para o banco D1 e o armazenamento KV. Fornece endpoints para leitura de logs, configurações e dados estruturados.

Bindings: D1 (csv-hub), KV (csv-config)

csv-aiFase 3

Proxy seguro para o Cloudflare AI Gateway. Permite que o frontend utilize modelos de IA (chat, resumo, análise, rascunho de e-mail) sem expor tokens no navegador.

Bindings: D1 (csv-hub), Secret (AI_GATEWAY_TOKEN), Secret (RESEND_API_KEY)

POST /chat — Chat completion (compatível com OpenAI)
POST /summarize — Resumo de texto (template pronto)
POST /analyze — Análise de dados (template pronto)
POST /draft-email — Rascunho de e-mail (template pronto)
GET /models — Lista modelos disponíveis
GET /usage — Estatísticas de uso

csv-email—

Endpoint genérico para envio de e-mails transacionais via Resend. Suporta HTML, texto simples, CC, BCC, reply-to e tags de rastreamento. Remetente padrão: Hub CSV <hub@mail.grupocsv.com>.

Bindings: Secret (RESEND_API_KEY)

csv-mailv1.0.0

Sistema de envio de e-mails agentico do Grupo CSV. Endpoint independente com autenticacao por API key propria, suporte a HTML, texto, template institucional (header/footer padrao), anexos (ate 25 MB), CC, BCC, reply-to e tags de rastreamento. Remetente padrao: Guilherme Thome <guilherme@mail.grupocsv.com>.

Bindings: D1 (csv-hub), Secret (RESEND_API_KEY), Secret (CSV_MAIL_API_KEY)

POST /send — Envio completo de e-mail
POST /send-template — Envio com template institucional
GET /status/:id — Consultar status via Resend
GET /logs — Listar ultimos e-mails enviados (D1)
GET /health — Health check

csv-webhook—

Recebe webhooks de formulários e ferramentas do Hub. Encaminha os dados para destinos configurados (URLs externas, e-mail ou ambos). Cada canal (ex: dataset-tea, feedback-proposta) possui destinos pré-configurados por segurança.

Bindings: D1 (csv-hub), Secret (RESEND_API_KEY)

csv-propostas—

Gera propostas comerciais em HTML a partir de um template, armazena o arquivo no R2 Storage e envia o link por e-mail via Resend. As propostas ficam acessíveis publicamente em propostas.axcare.com.br.

Bindings: R2 (csv-propostas), Secret (RESEND_API_KEY)

thera-contact—

Processa o formulário de contato do site thera.tech. Envia os dados por e-mail para contato@thera.tech via Resend.

Bindings: Secret (RESEND_API_KEY)

4. Sistema de Autenticação

O Hub CSV possui três modelos de autenticação distintos, cada um adequado ao tipo de portal e público. Todos são gerenciados pelo worker csv-auth e pelo script frontend hub-auth.js.

4.1. Admin Universal

O proprietário do sistema possui uma credencial mestra que concede acesso a todos os portais e ao painel administrativo. Ao fazer login com essa credencial em qualquer portal, o sistema reconhece automaticamente e concede acesso.

4.2. Portais de Parceiros (Autenticação Individual)

Portais: Unimed, Unihealth, ICDS.

Usuário acessa uma página protegida (ex: hub.grupocsv.com/unimed/).

hub-auth.js detecta ausência de token válido e exibe modal com abas "Login" e "Solicitar Acesso".

Login: Requer e-mail e senha individual de um usuário previamente aprovado.

Solicitar Acesso: Formulário com nome e e-mail. Gera uma solicitação pendente no D1 e notifica o admin por e-mail.

O admin aprova ou rejeita a solicitação via Painel Admin. Ao aprovar, define a senha do usuário.

Após aprovação, o usuário recebe e-mail de confirmação e pode efetuar login. Token válido por 24 horas.

4.3. Portais de Empresas (Senha Compartilhada)

Portais: AxiaCare, Thera, MedValor.

Usuário acessa uma página protegida (ex: hub.grupocsv.com/axia/).

hub-auth.js exibe modal com campo de senha (sem e-mail).

A senha fixa do portal é validada contra o valor armazenado na tabela portal_passwords do D1 (com fallback para valores padrão em memória).

Token de sessão é gerado e armazenado no localStorage. Válido por 24 horas.

As senhas dos portais de empresas podem ser alteradas em tempo real pelo Painel Admin, na aba "Senhas dos Portais CSV".

4.4. Deck (PIN de 4 Dígitos)

Usuário acessa hub.grupocsv.com/deck/.

Tela de bloqueio exibe 4 campos para o PIN.

PIN é validado contra um hash armazenado no localStorage.

"Esqueceu o PIN?" envia PIN temporário por e-mail via /deck/reset-pin e força redefinição.

5. Banco de Dados e Armazenamento

5.1. Cloudflare D1 (`csv-hub`)

Banco de dados SQL relacional (SQLite na edge). Principal fonte de verdade para dados estruturados.

users

Usuários dos portais de parceiros. PK: email. Campos: email, password, name, status (pending/active), created_at, updated_at.

user_tenants

Vínculo entre usuário e portal (tenant). PK composta: (user_email, tenant_id). Campos: status, approved_by, approved_at, created_at, updated_at.

access_requests

Solicitações de acesso aos portais. Campos: id, user_email, tenant_id, status (pending/approved/rejected), request_token, requested_at, approved_by_email, approved_at.

auth_sessions

Tokens de sessão ativos. PK: token. Campos: user_email, tenant_id, device_info, ip_address, user_agent, expires_at, created_at.

access_logs

Registro de acessos e ações nos portais. Campos: id, tenant_id, user_email, action, page_accessed, ip_address, user_agent, device_info, country, city, timestamp.

api_logs

Log de todas as requisições ao gateway. Campos: worker, method, path, status_code, origin, ip, user_agent, payload_size, response_time_ms, error, created_at.

portal_passwords

Senhas dos portais de empresas. PK: portal_id. Campos: password, updated_at, updated_by. Criada sob demanda pelo csv-auth.

email_logs

Log de e-mails enviados via Resend. Campos: from_addr, to_addrs, subject, resend_id, status, error, worker_origin.

5.2. Cloudflare KV (`csv-config`)

Armazenamento de chave-valor de baixa latência. Binding disponível nos workers csv-data e csv-cron para configurações dinâmicas. As senhas dos portais de empresas foram migradas para a tabela portal_passwords no D1, mas o KV permanece como recurso para futuras configurações que exijam leitura de altíssima velocidade.

5.3. Cloudflare R2 (`csv-propostas`)

Armazenamento de objetos compatível com S3. Usado para guardar propostas comerciais geradas pelo worker csv-propostas. Os arquivos ficam acessíveis publicamente via propostas.axcare.com.br.

6. Painel Administrativo

Acessível em hub.grupocsv.com/admin/, protegido por autenticação de admin. Permite gerenciar todo o sistema de autenticação e links públicos.

Aba	Funcionalidade
Senhas dos Portais CSV	Visualizar e alterar as senhas fixas dos portais de empresas (AxiaCare, Thera, MedValor). Alterações entram em vigor imediatamente.
Usuários Externos	Aprovar/rejeitar solicitações de acesso. Listar usuários aprovados com seus portais vinculados. Revogar acesso.
Links Públicos	Listar páginas publicadas em `/p/`. Revogar ou restaurar links públicos (altera o `registry.json` via commit no GitHub).
Log de Acessos Externos	Histórico de logins em portais externos, ordenado do mais recente ao mais antigo. Exibe e-mail, nome, portal e data.

7. Serviços Externos Integrados

O backend integra-se com serviços externos para funcionalidades específicas. Todas as chaves de acesso são armazenadas como Secrets nos Workers.

Serviço	Uso	Workers que Utilizam
Resend	Envio de e-mails transacionais (notificações, relatórios, propostas, formulários de contato)	csv-auth, csv-cron, csv-email, csv-mail, csv-propostas, csv-webhook, thera-contact
Cloudflare AI Gateway	Proxy para modelos de IA (chat, resumo, análise)	csv-ai
GitHub API	Commits automáticos no repositório (revogação de links públicos)	csv-auth

Domínios de E-mail Verificados (Resend)

Domínio	Uso Principal	Região
`mail.grupocsv.com`	Backend do Hub CSV (notificações, relatórios, propostas)	sa-east-1
`thera.tech`	Formulário de contato do site Thera	sa-east-1
`spectra.thera.tech`	Spectra AI	sa-east-1
`veritas.thera.tech`	Veritas	sa-east-1

8. Domínios e DNS

Todos os domínios são gerenciados via Cloudflare DNS. Os registros mais relevantes para a infraestrutura do Hub estão listados abaixo.

Subdomínio	Tipo	Destino	Função
`hub.grupocsv.com`	CNAME	grupocsv.github.io	Frontend do Hub (GitHub Pages)
`api.grupocsv.com`	AAAA	100::	API Gateway (Worker csv-gateway)
`api.thera.tech`	AAAA	100::	Worker thera-contact
`propostas.axcare.com.br`	CNAME	public.r2.dev	R2 Bucket (propostas)
`mail-api.grupocsv.com`	AAAA	100::	Worker csv-mail
`webhook.grupocsv.com`	A	192.0.2.1	Worker csv-webhook

Zonas Cloudflare

O ecossistema utiliza 9 zonas DNS no Cloudflare: axcare.ai, axcare.app, axcare.com.br, grupocsv.com, guithome.com.br, medvalor.med.br, theramed.ai, thera.med.br e thera.tech. Todas utilizam Google Workspace para e-mail corporativo (MX records).

9. Notas Técnicas

Tópico	Detalhe
SPA Navigation	O VitePress intercepta cliques internos. Páginas HTML standalone precisam do atributo `data-direct` nos links para forçar navegação completa.
Convenção de Tenant	O `csv-auth` usa colunas `tenant_id` e `user_email` no D1 (não "portal" e "email"). Aliases são suportados (ex: `axia` mapeia para `axiacare`).
Notificações	E-mails de notificação de login e solicitações de acesso são enviados via Resend para `contato@grupocsv.com`.
CORS	Todos os workers incluem headers CORS permissivos (`Access-Control-Allow-Origin: *`) para permitir chamadas do frontend em GitHub Pages.
Logging	Todas as requisições que passam pelo gateway são registradas na tabela `api_logs` com worker, método, path, status HTTP e tempo de resposta em milissegundos.
Sessões	Tokens de sessão têm validade de 24 horas. A limpeza automática de sessões expiradas ocorre semanalmente (domingo 03:00 BRT).
Links Públicos	Páginas em `/p/` são registradas no `registry.json`. A revogação/restauração é feita via commit automático no GitHub usando a API.

← Voltar à Infraestrutura Cognitiva