Arquitetura

O TermoTracing segue o padrão de projeto da Termotubos: backend em Rust e frontend em SvelteKit, organizados por feature, com as mesmas 7 operações e os mesmos nomes nos dois lados.

Features

Feature	Backend	Frontend
aplicativo	controller/aplicativo/, router/aplicativo.rs, model/aplicativo.rs	lib/modules/aplicativo/
sessao	controller/sessao/, router/sessao.rs, model/sessao.rs	lib/modules/sessao/
evento	controller/evento/, router/evento.rs, model/evento.rs	lib/modules/evento/
erro	controller/erro/, router/erro.rs, model/erro.rs	lib/modules/erro/
uso	controller/uso/, router/uso.rs, model/uso.rs	lib/modules/uso/

O frontend tem ainda o módulo autenticacao, que cuida do token do TermoAuth.

Rotas da API

Cada feature expõe as 7 operações:

Operação	HTTP
criar	POST /<feature>
buscarPaginador	GET /<feature>
buscarAutoComplete	GET /<feature>/autocomplete
buscarPeloFiltro	GET /<feature>/filtro
buscarPeloId	GET /<feature>/:id
atualizarPeloId	PATCH /<feature>/:id
deletarPeloId	DELETE /<feature>/:id

A exceção é evento: não tem POST /evento. Os eventos entram só por POST /evento/ingestao, a única rota pública. Todas as outras passam pelo verificarTokenAuth.

Backend

• axum + sqlx com PostgreSQL. Tudo do app, inclusive o _sqlx_migrations, fica no schema termotracing, nunca no public: os apps da Termotubos dividem o mesmo cluster.
• Ao subir, o backend cria o schema, aplica as migrations de backend/migrations/ e inicia a fila de processamento e a retenção.
• O pool tem tamanho e espera configuráveis (DATABASE_MAX_CONNECTIONS e DATABASE_ACQUIRE_TIMEOUT, padrão 10 conexões e 5 segundos).
• O CORS do painel aceita só a URL_FRONTEND; o da ingestão aceita qualquer origem.

Autenticação

O verificarTokenAuth espera Authorization: Bearer com um JWT EdDSA do TermoAuth:

• A chave pública vem do JWKS em TERMOAUTH_API_URL/.well-known/jwks.json, guardada em cache por kid. Um kid desconhecido só busca o JWKS de novo depois de 30 segundos.
• iss e aud precisam ser iguais a TERMOAUTH_URL; exp, iss, aud e sub são obrigatórios.
• Só passa role = employee. Os demais recebem 403; TermoAuth fora do ar dá 503.
• conta_id é o sub do token e conta_email é o email.

Frontend

• SvelteKit com adapter-static; a área /app roda só no navegador (ssr = false).
• O token chega do TermoAuth em #token= na URL e fica no sessionStorage. Sem token ou com 401, o app manda para o handoff do TermoAuth. O id do app no TermoAuth é termo-tracing.
• Cada Contexto<Feature>.ts é o único lugar que faz fetch e injeta o Bearer.
• O t.js em frontend/static/ é o SDK instalado nos sites; o próprio painel também o carrega.

Banco

Cinco tabelas, todas com conta_id e deletado:

Tabela	O que guarda
aplicativo	Site monitorado, chave, domínios e franquia
sessao	Uma aba de navegador num aplicativo
evento	Cada evento recebido
erro	Grupo de erros pela assinatura
uso	Aceitos e recusados por aplicativo e por dia

sessao, evento, erro e uso apontam para aplicativo com ON DELETE CASCADE. O diagrama completo fica em docs/database-erd.

Ambiente dev

Serviço	Porta
frontend	51110
backend	51111
docs-projeto (esta documentação)	51112
database-erd	51113
database-studio	51114

Todos sobem pela configuração de mesmo nome no .claude/launch.json.

Variáveis de ambiente

Onde	Variáveis
Backend	DATABASE_URL, DATABASE_MAX_CONNECTIONS, DATABASE_ACQUIRE_TIMEOUT, URL_FRONTEND, PORTA, TERMOAUTH_URL, TERMOAUTH_API_URL, RESEND_API_KEY, REMETENTE_AVISOS
Frontend	PUBLIC_API_URL, PUBLIC_TERMOAUTH_URL

Deploy

Os workflows ficam em .github/workflows/, um por ambiente e por lado:

	Backend	Frontend
Gatilho	Push em sandbox ou production que mexa em backend/**, ou manual	Manual
Build	cargo build --release	bun run build
Destino	Serviço systemd termotracing-backend	Serviço systemd termotracing-frontend (Node + sirv)

Ambiente	Painel	API
Sandbox	sandbox-tracing.termotubos.com.br	sandbox-api-tracing.termotubos.com.br
Production	tracing.termotubos.com.br	api-tracing.termotubos.com.br