Skip to content

Plano --- Arquitectura de Desenvolvimento Soberano (validado e reformulado)

Data: 2026-06-20 · Base: Arquitectura_Desenvolvimento_Soberano_JLB_2026-06-20.docx + sessão de validação\ Estado: para aprovação (modo planeamento --- nada será executado sem o teu OK)

Contexto

O documento da sessão da manhã tomou uma decisão estratégica sólida: consolidar todo o desenvolvimento no Claude Code, impor uma moratória de 12 meses a ferramentas novas, e proteger o princípio \"o processo não pode consumir o produto\". Os seis problemas levantados (§3 do documento) justificam bem o adiamento da arquitectura multi-camada agnóstica.

A validação contra o estado real da VPS (verificado por SSH a 2026-06-20) revelou que o documento precisa de três correcções antes de ser accionável:

  1. Factos desactualizados --- duas das \"prioridades a construir\" já estão em produção.

  2. Tensão de framing --- \"VPS = deployment only\" colide com a camada de runtime que tem de existir (brain, LiteLLM, Hermes).

  3. Soberania como princípio rígido --- o §8 (\"DeepSeek/Minimax excluídos, inalterável\") contradiz a tua intenção declarada de relaxar temporariamente para acelerar a colheita, e contradiz a própria config viva do LiteLLM (que já tem grupos DeepSeek).

Este plano corrige os três pontos, formaliza a soberania faseada por classificação de dados, e redefine o portefólio real dos próximos 90 dias.

1. Decisões confirmadas nesta sessão

Dimensão Decisão

Ambiente de desenvolvimento Claude Code exclusivo (MacBook 16\"), Opus agora / Sonnet quando otimizar

Hermes + skills-gateway (VPS) Manter como força-de-trabalho de runtime (scraping, pesquisa, ontologia, ingestão, enriquecimento). NÃO orquestra desenvolvimento.

Princípio VPS reformulado VPS = deployment + runtime de dados; sem NOVA camada de orquestração de dev acima do Claude Code

Soberania Faseada por classificação de dados + janela temporária relaxada (\~2 meses de colheita intensiva; revisão de re-bloqueio aos \~6 meses ou na 1ª app com dados privados --- o que vier primeiro)

LiteLLM (VPS) --- prioridade Free tier → low-cost pago (incl. modelos chineses) → premium/alta-segurança (last resort)

Teto de custo LiteLLM (VPS) \$100 → \$250/mês durante a colheita; revert para \$50/mês ao fechar. Alerto-te se \$250 travar a colheita.

Stack local M3 Manter instalada (infra de (Ollama+LiteLLM:4000+WebUI) soberania futura). Não entra no pipeline de colheita (não serve always-on).

Promoção a produção Sempre com aprovação explícita --- nunca automática (mantido do §8)

2. Correcções factuais ao documento

Verificado na VPS (containers a correr há 9 dias):

Documento diz Realidade Acção

§6.1 Vaultwarden = P1 Já LIVE (vault.joaoluisbrazao.cloud) Reescopar: não instalar \"instalar\" --- adoptar para CateringAssiste (2FA/contas) + centralizar segredos

§6.2 Expense Report = LIVE em produção desde 02-Jun Remover do portefólio \"pronto p/ build (er-backend/celery/frontend/minio) de \"a construir\". overnight\" Está feito.

§6.2/§6.3 OCR via Pipeline provado usa Tesseract + Reutilizar Doctr Celery (/opt/expense-report/) Tesseract, não introduzir Doctr

§8 \"DeepSeek/Minimax LiteLLM já tem Substituir por excluídos standard-deepseek/advanced-deepseek princípio faseado e (inalterável)\" versionado (secção 4)

§6.3 canal mail-triage antigo foi removido; existe Reutilizar o padrão \"mailtriage\" brain-mail-intake (SMTP→staging) brain-mail-intake para o intake de PDFs da CA

3. Arquitectura reformulada (espinha dorsal)

Dois planos que nunca competem:

  • Build-time --- Claude Code (MacBook 16\"): onde escreves/planeias/constróis. Dirigido por ti. Moratória de ferramentas novas em vigor.

  • Run-time --- VPS (Hermes + jb-skills-gateway): força-de-trabalho automática que executa o trabalho recorrente de dados (pesquisa, scraping, ontologia/toponímia, ingestão, enriquecimento), agendada por tempo/evento.

O brain (down_rabbit_hole), o LiteLLM e as apps live são serviços de runtime --- não violam \"Claude Code exclusivo\", que é sobre o ambiente de desenvolvimento.

Migração Hostinger → Hetzner: só quando o Hostinger atingir limites (a VPS já corre \~30 containers e está a 20% de disco --- não é \"modesta\"; vigiar memória).

4. Soberania faseada --- modelo e reconfiguração do LiteLLM

4.1 Princípio (substitui §8 \"inalterável\")

Durante a janela de colheita (dados genéricos públicos da internet), o roteamento de LLM prioriza custo. Para dados privados/organizacionais/pessoais, só modelos EU-jurisdição ou locais. A fronteira é um controlo técnico no LiteLLM, não uma promessa operacional. Re-bloqueio na 1ª app de produção com dados privados, ou aos \~6 meses.

4.2 GUARDA-FREIO OBRIGATÓRIO (pré-colheita)

Risco confirmado: o brain já não é limpo de dados privados --- tens 40 docs pessoais staged (brain_staging, ingest_channel=local_import, in_review: 16 notas pessoais + 8 Bear + geopolítica). Enriquecer \"o brain\" com modelos baratos expõe esses nós a jurisdição não-EU.

→ Antes de relaxar: segregar/quarentenar os nós de origem privada para que os modelos low-cost só vejam nós de origem pública. (Marcar/excluir o conjunto local_import e qualquer nó pessoal do pipeline de enriquecimento relaxado.) Sem isto, o relaxamento já toca dados que disseste querer proteger.

4.3 Reconfiguração do LiteLLM (VPS --- /opt/infrastructure/litellm/config.yaml)

Tiers por cadeia de fallback ordenada por custo:

  1. Free tier --- OpenRouter :free (gpt-oss-120b, qwen3-coder, nemotron, hermes-3), Groq, Gemini free (onde a quota permitir)

  2. Low-cost pago --- DeepSeek-v4, Qwen, GLM/Zhipu, Kimi (via OpenRouter) --- temporário, janela de colheita

  3. Premium / alta-segurança (LAST RESORT) --- Sonnet 4.6, Opus 4.7/4.8, Gemini 2.5 Pro --- só quando free+low-cost não dão qualidade para a TASK

Grupos separados por sensibilidade:

  • harvest-* (enriquecimento/colheita) → cadeia 1→2→3 acima

  • sovereign-* (qualquer call com dados privados) → só Mistral EU / local --- nunca cadeia 2

Parâmetros:

  • max_budget: \$100 → \$250 (reverter a \$50 ao fechar). Caps por-provider (\$10) e Gamine (€50) mantêm-se.

  • Gotcha conhecido (memória): HTTP 400 (créditos esgotados) não é re-tentado pelo fallback do LiteLLM (só 429/5xx). Os workers de enriquecimento têm de tratar 400 / pré-financiar provider. Mudança de env var → force-recreate, não restart.

  • Backup obrigatório antes: config.yaml.bak-pre-harvest-20260620.

4.4 Enriquecimento durável

Retomar o worker de enriquecimento (/opt/brain-import/ingest_markdown.py via run.sh) em modo durável (docker run -d / tmux / systemd --- não nohup & sobre SSH, que não persistiu), apontado aos aliases harvest-*. Máx. 2 workers (8 → 429). Alvo: concluir os nós reais pendentes.

5. Portefólio real --- próximos 90 dias (corrigido)

# App Estado real Nota

--- Vaultwarden ✅ live Adoptar para CA (2FA/contas), não instalar

--- Expense Report ✅ live Concluído; só follow-ups (#899 SSO (Eureekka+Gestso) José Rocha, #900/#901)

1 Reporting de a construir ERP→PDF→email→Tesseract Intervenções (reutilizar)→Postgres→dashboard. (CA) Confirmar com IT CA: trigger ERP + dump 2024. Maior ROI operacional.

2 JBSB / Second em curso Concluir enriquecimento; Hermes Brain --- corre os bots de prospecção colheita + temática. Base de tudo o resto. enriquecimento

3 Gamine --- depende de JBSB Multi-língua com legendas, sem Reaproveitamento estável síntese de voz. Não antes do de Conteúdo JBSB. (HMN)

4 Gamine --- depois de 2 e 3 A mais ambiciosa. Última. Market
Intelligence

CATALOG-FIRST: antes de qualquer skill nova de colheita, procurar em admin.joaoluisbrazao.cloud/#/github-repos (85 skills já existem).

6. Pilar nº1 --- disciplina do ciclo diário (a verdadeira alavanca)

O teu próprio Problema 5 (sem guardião técnico) + execução autónoma overnight = risco de output confiante-mas-errado que custa mais a desfazer. A alavanca de produtividade não é a ferramenta --- é a qualidade do spec e a verificação. Por isso:

  • Manhã: planeamento em modo-plano (Sonnet), specs de 4--5 tarefas com critérios de aceitação explícitos.

  • Fim do dia: carregar plano no Claude Code (modo auto, modelo potente).

  • Noite: execução + verificação obrigatória (testes/observação) antes de marcar \"feito\" --- nunca afirmar sucesso sem evidência.

  • Manhã seguinte: triagem do reporte, resolver críticos.

  • Staging-only para tudo; promoção a produção só com o teu OK (§8 mantido). A autonomia overnight escreve para staging, nunca para produção.

7. Varrimento de inventário / desinstalação (escopo)

Conforme §7.2 do documento --- inventariar antes de remover:

  • Remover: experiências de IDE/agente de dev fora do Claude Code (ex.: setups Cline/VSCodium/Continue.dev, se não usados), orquestradores de dev não-usados.

  • Manter: Hermes + skills-gateway (runtime de dados), brain, LiteLLM, apps live, stack local M3 (soberania futura).

  • Regra: não desinstalar nada sem confirmar que não serve produção.

8. Acções imediatas (após aprovação)

  1. Confirmar com IT CateringAssiste: ERP envia PDF ao fechar intervenção? Dump 2024 disponível?

  2. LiteLLM: backup config → reconfigurar tiers harvest-*/sovereign-* → subir cap p/ \$250 → force-recreate → testar cadeia de fallback (free→low-cost→premium).

  3. Guarda-freio: quarentenar nós de origem privada no brain_staging antes de relaxar o enriquecimento.

  4. Enriquecimento: relançar worker durável apontado aos harvest-*.

  5. Hermes: validar/repor agendamento limpo das skills de colheita (alguns crons estavam partidos no último audit).

  6. Inventário de ferramentas de dev a remover (lista para o teu OK antes de apagar).

  7. Reporting de Intervenções: preparar plano de implementação para o Claude Code (reutilizar Tesseract + padrão brain-mail-intake).

9. Verificação (como saberemos que funciona)

  • LiteLLM: call de teste resolve na ordem free→low-cost→premium; max_budget mostra \$250; grupo sovereign-* nunca rota para cadeia 2.

  • Guarda-freio: query ao brain_staging confirma que os nós local_import/pessoais estão excluídos do enriquecimento relaxado.

  • Enriquecimento: worker persiste após fecho da sessão SSH; contagem de nós enriquecidos sobe.

  • Hermes: skills de colheita disparam por agendamento (verificar last-run / logs).

  • Apps novas: correm em staging; nenhuma promoção automática a produção.

10. O que vou monitorizar e alertar

  • Se \$250/mês se tornar constrangimento que trave a colheita → aviso-te para decidires investir mais pontualmente.

  • Re-bloqueio de soberania: alerta na 1ª app de produção com dados privados, ou aos \~6 meses (≈Dez-2026).

  • Pressão de memória/disco na VPS (gatilho para Hetzner).

Nota sobre o documento original

Posso, se quiseres (fase de execução), gerar uma versão revista do .docx com estas correcções, ou manter este .md como o documento de arquitectura vivo que supersede o original.