Adapter (LGPDQuest) — ambientes

O Adapter é a aplicação de conformidade LGPD que consome o BravoCore como backend de IA. Ele tem quatro ambientes — dev, test, homolog e prod. Desde 14/09/2026, test compartilha o servidor de dev; homologação e produção têm servidores próprios. Todos são gerenciados por uma única instalação do Coolify, numa VPC dedicada em br-sao (São Paulo).

Esta página descreve esses ambientes: o que cada um serve, como o código chega neles e o que muda de um para o outro.

Os quatro ambientes

Ambiente	Front	API	Serve para
Dev	dev.adapter.bravonix.ia.br	api.dev.adapter.bravonix.ia.br	Integração contínua do time; origem da cópia inicial de test
Test	test.adapter.bravonix.ia.br	api.test.adapter.bravonix.ia.br	Testes da branch test, com cópia inicial de dev e dados separados
Homologação	homolog.adapter.bravonix.ia.br	api.homolog.adapter.bravonix.ia.br	Validação antes de produção; base restaurada a partir do ambiente antigo
Produção (nova)	prod.adapter.bravonix.ia.br	api.prod.adapter.bravonix.ia.br	Ambiente-alvo, no ar em paralelo com a produção atual

A produção que atende clientes ainda é a antiga

Quem atende cliente hoje é adapter.lgpdnow.com.br (com API em adapter.bravonix.api.br), na infraestrutura anterior. O ambiente prod.adapter.bravonix.ia.br roda com uma cópia dos dados e existe para validação — os dois convivem, cada um no seu endereço, até a virada de DNS ser autorizada. Não mande cliente para o endereço novo.

Por que os internos usam bravonix.ia.br

Ambientes internos ficam todos na zona bravonix.ia.br. A produção fica em lgpdnow.com.br porque é o endereço que os clientes já usam — trocá-lo é decisão comercial, não técnica.

O que compõe um ambiente

Os quatro têm o mesmo desenho: cinco aplicações (build por Dockerfile) e quatro bancos (recursos do Coolify, sem porta publicada na internet), mais um bucket de objetos próprio.

flowchart TB
    U["Usuário"]

    subgraph AMB["Um ambiente (dev / test / homolog / prod)"]
        FE["Front<br>nginx + build Vite"]
        API["adapter-api<br>Koa"]
        BC["BravoCore<br>Django"]
        CW["celery worker"]
        CB["celery beat"]
        DB1[("adapter-db<br>PostgreSQL + pgvector")]
        DB2[("bravocore-db<br>PostgreSQL + pgvector")]
        R1[("Redis — Koa")]
        R2[("Redis — Celery")]
    end

    COS[("Bucket de objetos<br>um por ambiente")]
    LF["Langfuse<br>tracing de LLM"]

    U --> FE
    U --> API
    FE --> API
    API --> BC
    API --> DB1
    API --> R1
    BC --> DB2
    BC --> R2
    R2 --> CW
    CB --> R2
    BC --> COS
    BC --> LF
    CW --> LF

Peça	Repositório	Papel
Front	adapter (/frontend)	Interface web, servida por nginx
adapter-api	adapter-api	API principal (Koa), dona do login e dos processos
BravoCore	BravoCore (/backend)	API de IA/RAG, admin Django e documentação da API
celery worker	BravoCore	Processamento assíncrono (ingestão de documentos, agentes)
celery beat	BravoCore	Tarefas agendadas

Roteamento — um domínio, dois backends

O domínio de API de cada ambiente atende duas aplicações, divididas por caminho:

Caminho	Vai para
/api, /admin, /static	BravoCore (Django)
Todo o resto (/)	adapter-api (Koa)

Dois logins parecidos, em aplicações diferentes

POST /v1/auth/login é o login do Adapter (Koa). POST /api/v1/auth/login/ é o login do BravoCore (Django). Chamar a rota errada devolve 401 e parece senha inválida.

O admin do Django fica em /administrator/

/admin não existe como rota da aplicação — mas é o prefixo que roteia o tráfego até o Django, porque a regra casa por texto (/admin cobre /administrator). Por isso ele aparece na tabela acima.

Branches — uma por ambiente

Repositório	Dev	Test	Homologação	Produção
adapter	dev	test	homolog	main
adapter-api	dev	test	homolog	main
BravoCore	develop	test	homolog	main

O BravoCore usa develop, não dev

É a única exceção. Apontar a branch errada falha no clone e o painel mostra apenas um erro genérico de deploy.

Como o código chega no ambiente

flowchart LR
    A["Merge na branch<br>do ambiente"] --> B["Webhook<br>para o Coolify"]
    B --> C["Build na máquina<br>dedicada de build"]
    C --> D["Imagem publicada<br>no registry privado"]
    D --> E["Servidor do ambiente<br>baixa e sobe o container"]

• O build não roda no servidor do ambiente: existe uma máquina só para isso, e a imagem pronta vai para o registry privado da Bravonix.
• Nome da imagem: <aplicação>-<ambiente>, com a tag sendo o commit. Cada ambiente tem seu próprio repositório de imagem — o mesmo commit em ambientes diferentes gera imagens diferentes, porque as variáveis de build também são diferentes.
• Deploy bem-sucedido troca o container, e a troca tem alguns segundos de 502. Deploy que falha não derruba nada: o container antigo só sai depois que o novo sobe. Isso decide a janela de deploy em ambiente que atende usuário.

Variável do front é de build, não de execução

O endereço da API usado pelo front (VITE_*) entra na hora do build. Mudar a variável sem refazer o build não muda nada — e o sintoma é o login falhar.

Dados — o que cada ambiente contém

Ambiente	Origem dos dados	Contém dado pessoal?
Dev	Base de desenvolvimento existente	Há contas cadastradas; não presumir ausência de dados pessoais
Test	Cópia de dev em 14/09/2026, sem sincronização posterior	Tratar com os mesmos cuidados da origem; há contas copiadas
Homologação	Restaurado do ambiente antigo de homologação	Sim — há usuários reais de cliente na base do BravoCore
Produção (nova)	Cópia da produção atual	Sim

Cópias de dados precisam preservar as chaves de criptografia

O BravoCore guarda e-mail cifrado no banco e o Adapter cifra dados de 2FA. Restaurar um dump de um ambiente em outro sem levar as chaves não dá erro de deploy: o ambiente sobe, responde normalmente e os campos aparecem em branco, com usuários que não conseguem entrar. Na migração de produção e na cópia inicial de dev para test, as chaves de cifra são copiadas da origem. Segredos de sessão e assinatura de test são próprios.

Nas chaves de banco e de Redis vale o contrário: são novas em cada ambiente, porque autenticam em vez de cifrar.

Cada ambiente também tem bucket de objetos próprio, com credencial restrita a ele: credencial de dev não alcança arquivo de produção, e apagar um documento no ambiente novo não toca no arquivo do cliente.

Observabilidade — Langfuse único

Os ambientes usam uma instância só do Langfuse, com projetos dev, homolog e prod. Test herdou a configuração de observabilidade de dev; não tem projeto exclusivo:

langfuse-2608.bravonix.ia.br

Backend e worker precisam de configuração própria. Consulte a página do Langfuse para configurar e validar cada ambiente.

Tracing falha em silêncio

Quando o endereço do Langfuse está errado, a aplicação não dá erro, não fica lenta e não registra nada no log: os traces simplesmente não aparecem. Se um ambiente parar de aparecer no Langfuse, o primeiro lugar a olhar é a variável que aponta para ele.

Backup

O que é salvo	Frequência	Onde
Bancos de dev, homolog e prod	Diário, horários escalonados	Armazenamento de backup já configurado
Os dois PostgreSQL de test	Diário, 00h30 e 00h45 (Fortaleza)	Armazenamento existente, com diretórios exclusivos
Configuração do Coolify (variáveis e acessos dos quatro)	Diário	Bucket próprio
Volumes do Langfuse	Diário	Bucket próprio

• Dev, homolog e prod mantêm a política existente de retenção de 14 dias. Test usa diretórios separados no armazenamento de backup existente.
• Alerta por e-mail quando um backup falha, quando o arquivo não chega ao destino e também quando o backup deixa de rodar — a falha silenciosa é o caso que mais engana.
• As restaurações dos ambientes anteriores foram testadas em destino descartável. Em test, a cópia inicial foi conferida por contagem de tabelas e linhas, e os primeiros backups concluíram com sucesso; a restauração desses novos backups ainda não foi ensaiada.

O backup mais importante não é o dos ambientes

É o da configuração do Coolify: ele guarda as variáveis e as chaves de acesso dos quatro ambientes de uma vez. Perder essa máquina sem cópia é perder a configuração dos quatro — e a cópia só é útil junto com a chave que decifra as variáveis.

Particularidades de test

Atualizado em 14/09/2026.

• Branch test nos três repositórios; publicação automática nas cinco aplicações.
• Compartilha CPU, memória e disco com dev. Testes de carga podem afetar os dois ambientes.
• Dois PostgreSQL copiados de dev e dois Redis novos, inicialmente vazios. Bancos, senhas, volumes e filas são separados, sem portas públicas.
• Bucket próprio com 23 arquivos copiados de dev e conferidos por hash. Alterações posteriores não são sincronizadas. A pasta de mídia é compartilhada apenas pelos processos de test.
• Envio de e-mails reais habilitado em 15/09/2026, pelo Resend, com a mesma credencial de homologação. Recuperação de senha e convites podem enviar mensagens reais; use destinatários de teste autorizados.
• Integrações externas e observabilidade foram herdadas de dev; não representam isolamento completo de contas externas.
• Administração do BravoCore, documentação da API, saúde do Adapter e saúde do BravoCore.
• Login do Adapter validado até a tela de documentos legais pendentes; o aceite cabe ao usuário. Login administrativo do BravoCore, integração entre APIs e tarefa de fila foram validados. Isso não equivale à homologação completa de OCR, ingestão ou respostas dos agentes.

Convenção de nomes

Servidores seguem adapter-<NN>-<ambiente>-<YYMM>: o produto na frente, número apenas para ambiente (01-dev, 02-homolog, 03-prod), infraestrutura sem número, e a data de criação no fim — nessa ordem porque só assim a listagem alfabética fica em ordem cronológica.

O nome do servidor não diz quem está servindo o endereço

A regra nasceu de um problema real: nomes com "novo" e "produção" espalhados por máquinas que serviam outra coisa. Quem responde por um domínio é o DNS, não o nome da máquina.

Troubleshooting

Sintoma	Causa provável	O que fazer
Login devolve 401 com credencial certa	Rota trocada entre Adapter (/v1/auth/login) e BravoCore (/api/v1/auth/login/)	Conferir qual das duas aplicações deveria autenticar
Login falha depois de mudar o domínio	Variáveis VITE_* do front são de build	Atualizar a variável e refazer o build
Caminho da API responde 404 vindo da aplicação	Prefixo do caminho sendo removido antes de chegar no backend	Verificar se a aplicação já serve naquele caminho
Deploy falha logo no início, sem log útil	Branch inexistente no repositório (o BravoCore usa develop)	Conferir a branch configurada
Ambiente sobe, responde 200, mas quebra no primeiro uso	Banco vazio — migrations não aplicadas	Conferir se o passo de migração rodou no deploy
Traces pararam de aparecer no Langfuse	Endereço do Langfuse errado (falha silenciosa)	Conferir a variável do ambiente e o projeto de destino
Erro 502 por alguns segundos	Troca de container em deploy bem-sucedido	Comportamento esperado; escolher a janela de deploy

Onde estão as credenciais

Acessos ao painel, aos bancos e às contas de serviço ficam com a equipe de desenvolvimento — nunca nesta wiki. Solicite ao responsável pelo ambiente.