1. Sumário

O Toolbox FRM é um conjunto de 4 ferramentas internas de produtividade: cruzamento de arquivos, normalização de dados, gerador de texto alternativo (alt text) e design instrucional, mais um painel de administração. O uso é exclusivo de colaboradores da FRM, autenticados via SSO corporativo (Microsoft Entra ID). O login em si é gerenciado pelo Amazon Cognito, que faz a ponte entre a aplicação e o SSO da FRM.

Este documento dá uma visão geral de como o ambiente funciona: a arquitetura, os serviços AWS usados e o que cada um faz, o fluxo de autenticação, como o frontend conversa com o backend, e onde procurar quando algo não funciona como esperado. A operação profunda da infraestrutura (deploy, provisionamento, políticas de acesso) é mantida pela CloudFaster, responsável técnica pelo ambiente.

2. Evolução do projeto

O Toolbox nasceu como uma aplicação 100% estática: HTML, CSS e JavaScript, sem backend e sem login. As duas ferramentas de IA (gerador de alt text e design instrucional) chamavam a OpenAI diretamente do navegador, usando uma chave de API que o próprio usuário colava.

Hoje a arquitetura é full-stack na AWS. As principais mudanças:

3. Arquitetura geral

O frontend é estático e fica na borda da rede, protegido pelo AWS WAF (firewall de aplicação). O backend é serverless: as chamadas de API chegam pelo Amazon API Gateway, são roteadas para funções sob demanda no AWS Lambda, e essas funções conversam com o Amazon Bedrock (IA), o Amazon DynamoDB (banco de dados) e o Amazon SQS (fila de processamento assíncrono). A identidade é cuidada pelo Amazon Cognito, integrado ao SSO corporativo da FRM.

Clique no diagrama para ampliar.

Diagrama de arquitetura dos serviços AWS

Perspectiva dos serviços AWS:

Clique na imagem para ampliar.

4. Autenticação

O login usa o Amazon Cognito (Hosted UI), federado com o Microsoft Entra ID via SSO. O usuário nunca digita senha diretamente na aplicação: a autenticação acontece inteiramente no provedor corporativo. Depois do login, o Cognito recebe os grupos do Active Directory do usuário e usa isso para decidir quem tem acesso ao painel de administração.

Clique no diagrama para ampliar.

5. Frontend

O frontend é estático: HTML, CSS e JavaScript, sem framework. Cada ferramenta é uma página independente. Os arquivos ficam hospedados no Amazon S3 (armazenamento de objetos privado, sem acesso direto pela internet) e são entregues pelo Amazon CloudFront (rede de distribuição de conteúdo) com HTTPS.

6. Backend assíncrono

O backend combina dois padrões. Para upload de arquivo puro, o navegador envia direto para o Amazon S3, sem passar pelo backend. Para as operações de IA, que levam de dezenas de segundos a minutos, o sistema enfileira o pedido no Amazon SQS e devolve uma resposta imediata; uma função do AWS Lambda processa em segundo plano, e o navegador é avisado do resultado assim que fica pronto.

Clique no diagrama para ampliar.

Se uma tarefa falhar depois de algumas tentativas, ela vai para uma fila separada de mensagens não processadas, em vez de se perder. Isso permite investigar depois o que deu errado, sem que o pedido do usuário simplesmente desapareça.

Escolha do modelo de IA (Bedrock)

Cada ferramenta que usa IA deixa o usuário escolher, entre alguns modelos, qual deles vai gerar o resultado (velocidade x custo x qualidade). Essa escolha já é só uma decisão de tela: o backend aceita qualquer modelo permitido na conta AWS, sem precisar de mudança de código no lado do servidor. Isso foi organizado num arquivo único, compartilhado por todas as ferramentas — /js/bedrock-models.js — que lista os modelos disponíveis (nome, preço, se aceita imagem) e sabe desenhar o seletor na tela.

<!-- index.html da ferramenta nova, logo apos config.js/auth.js -->
<script src="/js/bedrock-models.js"></script>

<!-- espaco vazio onde os botoes de modelo aparecem -->
<div class="toggle-group-grid" id="modelPicker" role="radiogroup" aria-label="Selecione o modelo de IA"></div>

// app.js da ferramenta nova

// escolhe quais modelos aparecem nessa ferramenta
const TOOL_MODEL_IDS = [
  'us.amazon.nova-lite-v1:0',
  'us.anthropic.claude-haiku-4-5-20251001-v1:0',
];
let selectedModel = TOOL_MODEL_IDS[0];

renderModelPicker(document.getElementById('modelPicker'), TOOL_MODEL_IDS, selectedModel);
wireModelPicker(document.getElementById('modelPicker'), modelId => { selectedModel = modelId; });

// manda junto no pedido pro backend -- o backend ja sabe usar
const token = await Auth.getValidToken();
fetch(API_CONFIG.restUrl + '/minha-ferramenta/start', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer ' + token, 'Content-Type': 'application/json' },
  body: JSON.stringify({ modelId: selectedModel }),
});

7. Recursos AWS explicados

Esta seção detalha cada peça da infraestrutura AWS usada no projeto e para que ela serve, em linguagem simples. A ideia é que qualquer pessoa do time, mesmo sem experiência prévia em AWS, consiga entender o que cada serviço faz aqui.

Armazenamento de arquivos (Amazon S3)

O Amazon S3 guarda arquivos na nuvem, como uma pasta compartilhada, mas com muito mais escala e sem servidor pra manter. O projeto usa três tipos de bucket (nome que a AWS dá a cada "pasta" no S3), um conjunto por ambiente:

Funções sob demanda (AWS Lambda)

O AWS Lambda executa código só quando alguém chama, sem precisar de um servidor ligado o tempo todo. Cada função é pequena e faz uma coisa específica.

A tabela abaixo detalha as 12 funções: qual ferramenta ou ação do site dispara cada uma, quando ela dispara, o tamanho aproximado do código (linhas), e o que ela faz.

Por que existem duas funções para uma coisa "só"

Três pares desta tabela parecem redundantes à primeira vista. Não são: cada divisão existe por um motivo específico de arquitetura.

alt-text-start e alt-text-worker. Por que não é uma função só? Porque elas têm velocidades muito diferentes. Enfileirar um pedido leva menos de 1 segundo; gerar o texto alternativo via IA pode levar minutos. Se fosse uma função só, o navegador ficaria esperando a resposta HTTP travada até a IA terminar, e o Amazon API Gateway tem um limite de 30 segundos por chamada REST: a chamada estouraria esse limite antes da IA terminar. Separar em duas resolve isso: alt-text-start responde na hora (o usuário não fica esperando), e alt-text-worker processa em segundo plano, sem prazo apertado.

di-start, di-resource-start e di-design-system. As três enfileiram trabalho, mas em momentos e escopos diferentes do fluxo do Design Instrucional: di-design-system roda primeiro e sozinha (não enfileira, responde na hora) para definir a identidade visual do curso. Depois, di-start roda uma vez por curso, para gerar só a estrutura (o esqueleto: tópicos e lista de recursos). Só depois disso, di-resource-start roda uma vez para cada recurso individual que o usuário decide gerar. Ou seja: não é a mesma operação feita duas vezes, é uma sequência de três fases com escopos diferentes (curso inteiro → estrutura → um recurso por vez), o que permite ao usuário revisar a estrutura antes de gastar tempo e custo de IA gerando o conteúdo completo de cada página.

ws-connect e ws-disconnect (e por que a segunda "não faz nada"). Toda ferramenta com IA abre uma conexão WebSocket assim que a tela carrega, para receber o aviso em tempo real quando a tarefa termina. Essa conexão passa por três funções, uma para cada momento do ciclo de vida. ws-connect roda quando o navegador abre a conexão, e só confere se o usuário está autenticado, sem gravar nada. ws-subscribe roda logo depois, quando o navegador diz "quero acompanhar essa tarefa específica": ela grava o identificador da conexão dentro do próprio registro da tarefa no Amazon DynamoDB, para saber para onde mandar o aviso quando o processamento terminar. ws-disconnect roda quando o navegador fecha a conexão, por exemplo ao fechar a aba, e essa função não faz nada.

Não faz nada porque não há nada para fazer. O identificador da conexão não vive numa tabela própria de "conexões ativas": vive dentro do registro da tarefa, gravado ali pela ws-subscribe, e esse registro já expira sozinho depois de alguns dias. Não existe uma segunda cópia da informação que precise ser apagada quando a conexão cai. Se mais tarde o sistema tentar avisar uma conexão que já fechou, a chamada falha de um jeito esperado, sem quebrar nada, e o código já sabe ignorar esse erro. O navegador também pergunta o status a cada 3 segundos por conta própria (polling), então mesmo se o aviso em tempo real falhar, o resultado chega de qualquer jeito. É uma escolha de arquitetura enxuta: menos uma tabela para manter, sem perder nada.

Fila de mensagens (Amazon SQS)

Uma fila guarda pedidos até que alguém tenha capacidade de processá-los, em vez de deixar o usuário esperando a resposta na hora.

Porta de entrada da API (Amazon API Gateway)

Toda chamada da aplicação passa pelo Amazon API Gateway antes de chegar numa função Lambda. Existem dois tipos: um REST, pra chamadas normais de pedido/resposta, e um WebSocket, pra manter uma conexão aberta e avisar o navegador em tempo real quando uma tarefa termina. Na conta AWS, cada tipo existe como uma API separada por ambiente, quatro no total:

As rotas abaixo são idênticas nos dois ambientes, só muda a API que a chamada acessa:

No lado WebSocket, três eventos cobrem o ciclo de vida da conexão: abrir ($connect), fechar ($disconnect) e acompanhar uma tarefa específica (subscribe).

Banco de dados (Amazon DynamoDB)

O DynamoDB é um banco de dados que responde rápido mesmo com muitos acessos ao mesmo tempo, sem precisar de um administrador de banco cuidando dele. É um banco gerenciado e serverless: ninguém do time precisa instalar, atualizar ou dimensionar um servidor de banco de dados, e o projeto paga só pelas leituras e gravações que realmente acontecem, não por um servidor ligado 24 horas por dia. Para o volume de dados deste projeto (status de tarefas, registros de uso), essa é a escolha mais econômica e com menos manutenção disponível na AWS.

Em homologação, as tabelas de Tarefas e Uso têm o sufixo -hmg (frm-toolbox-jobs-hmg, frm-toolbox-usage-logs-hmg) — a de Usuários é a mesma nos dois ambientes. São cinco tabelas reais no total: duas por ambiente mais uma compartilhada.

Inteligência artificial (Amazon Bedrock)

O Amazon Bedrock habilita a aplicação a usar diversos modelos de IA generativa de diferentes fornecedores por trás de uma única interface, sem precisar integrar com cada fornecedor separadamente. Hoje a conta AWS do projeto tem 85 modelos catalogados no Bedrock, dos quais 77 estão ativos e disponíveis para uso. Desse catálogo inteiro, o Toolbox está de fato integrado a 8 modelos, das famílias Claude (Anthropic), Nova (Amazon), Mistral, Moonshot AI (Kimi) e GPT-OSS (OpenAI, rodando no Bedrock). O usuário escolhe o modelo na própria tela, dependendo do quanto de qualidade e velocidade precisa para aquela tarefa.

8. Ambientes (hmg / prod)

Existem dois ambientes completos, hmg (homologação) e prod (produção), rodando lado a lado. Toda mudança é testada em hmg antes de chegar em prod. É assim que o time garante que uma alteração não quebra o que já está no ar. O que é compartilhado entre os dois ambientes é o Amazon Cognito (login) e o AWS WAF (proteção de borda); todo o resto (Amazon S3, Amazon DynamoDB, funções Lambda) existe em cópias separadas por ambiente.

Clique no diagrama para ampliar.

9. Como contribuir: git e deploy

Esta seção é o passo a passo prático para quem vai desenvolver no projeto: como buscar o código, salvar uma alteração, publicar, e como uma mudança chega em homologação e depois em produção. Não é preciso decorar nada. É só voltar aqui sempre que precisar.

As três branches e o papel de cada uma

O caminho é sempre o mesmo, sem atalho: branch da tarefa → Pull Request → hmg → Pull Request → main. Ninguém publica direto em hmg ou main: as duas são protegidas e só aceitam mudanças via Pull Request (mais detalhe adiante).

Exemplos práticos: o que cada uma faz

A diferença entre as três é o que acontece quando o código chega nelas. Só uma coisa muda de um lugar para o outro: onde o código está — o próprio código é sempre o mesmo.

git checkout hmg
git pull
git checkout -b fix/ajusta-limite-upload
# edita os arquivos, testa localmente...
git add .
git commit -m "ajusta limite de upload"

git push -u origin fix/ajusta-limite-upload
gh pr create --base hmg --head fix/ajusta-limite-upload \
  --title "Ajusta limite de upload" --body "O que mudou e por quê"
gh pr merge --merge

gh pr create --base main --head hmg \
  --title "Promover hmg para produção" \
  --body "Mudanças validadas em hmg, prontas para ir ao ar"
gh pr merge --merge

Passo a passo — de uma pasta vazia até o ar

1. Trazer o código para a máquina (só na primeira vez)

   Com uma pasta vazia, o comando abaixo baixa o repositório inteiro:

   git clone git@github.com:Fundacao-Roberto-Marinho/toolbox.git
   cd toolbox

2. Criar a branch da tarefa (uma nova a cada mudança)

   A partir da hmg atualizada, nunca da main diretamente. É uma branch nova para cada tarefa, com prefixo feat/, fix/, chore/ ou docs/ + descrição curta em kebab-case:

   git checkout hmg
   git pull
   git checkout -b fix/ajusta-limite-upload

3. Testar localmente, antes de publicar qualquer coisa

   Nada aqui toca hmg ou o GitHub, é só a sua máquina. Ferramentas sem chamada de IA (cruzamento de arquivos, normalização de dados) abrem direto pelo navegador: dois cliques no index.html da pasta da ferramenta já basta. Ferramentas com chamada de IA (gerador de alt text, design instrucional) precisam de um servidor local, por causa de CORS:

   python3 -m http.server 8080
   # depois abrir http://localhost:8080 no navegador

   Pode testar e ajustar quantas vezes quiser aqui. Só entra na história do time no próximo passo, o commit.

4. Salvar uma alteração: o commit

   Depois de editar um arquivo, o commit salva essa alteração no histórico local do git. Ainda só na sua máquina, ninguém mais vê isso ainda:

   git add caminho/do/arquivo.js
   git commit -m "descreve o que mudou e por quê"

5. Publicar a branch: o push

   O push é o que envia os commits da sua máquina para o GitHub. Antes do push, a mudança existe só localmente; depois, o time inteiro consegue ver a branch. Só precisa de -u na primeira vez; depois é só git push:

   git push -u origin fix/ajusta-limite-upload

6. Abrir o Pull Request (PR)

   No GitHub, abrir um Pull Request da sua branch (a branch da tarefa) contra a base hmg. O PR dispara automaticamente uma checagem de qualidade (sintaxe, testes), sem tocar em nada na AWS ainda.

   gh pr create --base hmg --head fix/ajusta-limite-upload \
     --title "Título curto da mudança" \
     --body "O que mudou e por quê"

7. Revisar e mergear em hmg = deploy automático de homologação

   Hoje não existe uma segunda pessoa aprovando por padrão: quem abriu o PR pode revisar e mergear direto. A responsabilidade de conferir antes de ir pro ar é de quem faz o merge, então vale a pena dar uma última olhada no diff e no resultado do CI antes de confirmar.

   gh pr diff                 # ve o que vai entrar
   gh pr checks                # confere se o ci.yml passou
   gh pr merge --merge

   O merge dispara automaticamente o deploy para o ambiente de homologação. Nenhum passo manual adicional. Em poucos minutos a mudança está em toolbox-hmg.frm.org.br, pronta para ser validada.

8. Promover para produção

   Depois de validado em hmg, abre-se um segundo Pull Request, agora de hmg contra main. Mesmo fluxo: revisa e mergeia. Ao mergear, o deploy de produção dispara automaticamente, e a mudança vai para toolbox.frm.org.br.

   gh pr create --base main --head hmg \
     --title "Promover hmg para produção" \
     --body "Mudanças validadas em hmg, prontas para ir ao ar"
   gh pr merge --merge

O que protege main e hmg

As duas branches têm as mesmas regras de proteção:

• Ninguém publica direto nelas, só via Pull Request.
• Não é permitido apagar essas branches nem reescrever o histórico delas.

Clique no diagrama para ampliar.

10. Suporte e primeiros passos

Quando algo não funciona como esperado, o primeiro passo é isolar onde está o problema:

11. Glossário

Termos gerais

Serviços AWS usados neste projeto

12. Prompts para Claude Code

Quem não tem acesso à conta AWS consegue fazer todo o ciclo de contribuição — do commit até conferir se a mudança já está no ar — usando o Claude Code CLI na própria máquina, sem precisar decorar comandos de git ou gh. O Claude Code já lê sozinho o CLAUDE.md deste repositório (não precisa colar nada dele no prompt) e por isso já segue as regras do projeto: cria a branch da tarefa com o prefixo certo, sempre pergunta antes de mergear, e trata "promover para produção" como uma ação separada que pede confirmação extra. Basta colar o prompt e responder as perguntas de confirmação quando o Claude Code fizer — mas essas perguntas não substituem uma segunda pessoa revisando: é você mesmo quem aprova o próprio merge, então vale conferir a esteira antes de confirmar (os passos 6 e 7 abaixo já cobrem isso, nessa ordem).

1. Ver o que já mudou antes de começar

Confere o status do meu repositório: em que branch eu estou, o que já mudou e se tem alguma alteração ainda não commitada.

2. Criar a branch da tarefa

Crie uma branch nova pra eu trabalhar nesta mudança, a partir da hmg atualizada: [descreva em uma frase o que você vai mudar].

3. Revisar as mudanças antes de commitar

Antes de eu commitar, me mostra um resumo do que mudou nos arquivos.

4. Fazer o commit

Faça o commit só das alterações relacionadas a esta tarefa — me mostra antes quais arquivos vai incluir — com uma mensagem que explique por que eu mudei isso, seguindo o padrão de commit deste projeto.

5. Publicar a branch e abrir o Pull Request pra hmg

Publique minha branch no GitHub e abra um Pull Request dela contra a hmg.

6. Checar se a esteira rodou e passou em hmg

Confirma se a esteira do GitHub Actions já rodou pro meu Pull Request e se passou tudo certo.

7. Mergear o Pull Request em hmg

Pode mergear esse Pull Request em hmg?

O Claude Code sempre pergunta antes de executar o merge, mesmo que o CI esteja verde — e sempre pergunta também se quem roda o merge é ele mesmo ou se é você, manualmente pelo GitHub. Responda as duas perguntas para o merge acontecer. Se a esteira do passo 6 não tiver passado, não confirme — investiga o erro primeiro.

8. Promover hmg para produção

Quero levar pra produção o que já validamos em hmg.

Essa é uma ação separada e mais sensível: o Claude Code sempre confirma com você antes mesmo de abrir o Pull Request pra main, e confirma de novo antes de mergear — as mesmas duas perguntas do passo anterior, repetidas para produção. Importante: esse Pull Request leva pra produção tudo que estiver em hmg no momento, não só a sua mudança — se mais alguém mergeou algo em hmg nesse meio tempo, vai junto. Se não tiver certeza do que está diferente entre hmg e main, peça pro Claude Code listar antes de confirmar.

9. Checar se a esteira rodou e passou em main, e se já está em produção

Confirma se a esteira do GitHub Actions rodou e passou pro último merge em main, e se a mudança já está valendo em produção.