Infraestrutura Técnica

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

1.1. Central de Documentos

A Central de Documentos é um domínio privado e multi-tenant separado do gateway geral. O frontend compartilhado em /documentos/ chama diretamente o control plane csv-documents no domínio documentos-api.grupocsv.com. O Worker valida a sessão pelo Service Binding do csv-auth e mantém autorização documental no D1 dedicado.

Os tenants publicados são grupo-csv, unimed, unihealth, icds e 2im. A pesquisa foi validada pela Central/Extensio nos cinco tenants, incluindo isolamento, políticas, troca de versão, exclusão lógica e reconstrução de um documento retirado. O Worker 0389d7b4-eed6-4b60-b0d1-bdff6e25760b, fonte 094c8871e65c5f6d9ae0c9d6f0cbff8c107620b9, recebe 100% do tráfego. Esta versão do Hub habilita a busca após essa validação; a sessão humana no navegador permanece não aferida. O serviço isolado está na versão 2.1.0, schema 2. Panta v1 e seu MCP continuam independentes e preservados nas portas 8090 e 8091. Consulte a documentação canônica da Central de Documentos para lifecycle, agentes, OpenAPI, links públicos e estado de entrega.

Uso cotidiano: manual ilustrado da Central e manual do Panta v2. Os manuais descrevem os controles; não substituem a confirmação operacional nem a demonstração pendente a Guilherme.

Ao encerrar a validação em 16/09/2026, os cinco canários estavam excluídos logicamente, com consulta 404 e busca sem resultados. Limites da verificação: não houve novo reinício da VPS nem restauração integral do volume a partir de backup nesta rodada. Reconstrução de documento não equivale a recuperação integral de desastre.

A sincronização usa /internal/v2/documents/sync e revisões monotônicas no D1 (panta_sync_state). Só uma revisão confirmada entra no escopo da pesquisa. O cron reconcilia a cada cinco minutos, além do tempo de fila e processamento. A busca é lexical e limita o escopo a 500 documentos autorizados; excesso retorna 422 search_scope_too_large, sem corte silencioso. A credencial exclusiva fica em configuração protegida; nenhum token interno chega ao navegador ou ao agente final.

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

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.

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.

4.3. Portais de Empresas (Senha Compartilhada)

Portais: AxiaCare, Thera, MedValor.

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)

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.

5.2. Outros Bancos D1

5.3. Cloudflare KV (9 namespaces)

Armazenamento de chave-valor de baixa latência distribuído globalmente.

5.4. Cloudflare R2

Armazenamento de objetos compatível com S3, distribuído globalmente.

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.

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.

Domínios de E-mail Verificados (Resend)

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.

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