Formatloom: uma interface pequena com limites de engenharia sérios

Como o processamento local no navegador, os limites explícitos do parser, os testes e o caminho documentado de implantação definem o Formatloom.

O Formatloom é uma ferramenta pública para formatar e validar JSON, converter JSON e YAML e mostrar quando uma conversão pode perder significado. A interface é pequena. A engenharia não se resume a uma área de texto e um botão porque a entrada pode conter configuração ou dados de API que devem permanecer próximos de quem os está usando.

Este estudo de caso documenta decisões evidenciadas pelo produto em funcionamento e pelas notas técnicas públicas da Mirtilo IO. O repositório de implementação é privado; esta página não apresenta inspeção pública do código-fonte como evidência. Ele não alega crescimento de usuários, receita, resultados de clientes ou histórico operacional em alta escala.

O método de trabalho por trás desses limites está descrito no artigo Engenharia assistida por IA: evidência acima do output.

Problema

Formatadores online são convenientes até que o documento contenha algo privado ou operacionalmente sensível. Enviar esse documento para um serviço de processamento desconhecido muda o modelo de risco antes de a pessoa receber qualquer valor.

O produto precisava tornar o trabalho com dados estruturados rápido, mantendo o documento no navegador. Também precisava tornar visível a perda durante conversões. Uma ferramenta que remove comentários, aliases ou precisão numérica silenciosamente pode produzir uma saída que parece válida, mas mudou de significado.

Restrições

A fronteira foi escrita antes da implementação:

o processamento de JSON/YAML fica no navegador;
não há sistema de contas, banco de dados da aplicação, área de trabalho salva, endpoint de upload ou API de processamento;
a entrada é limitada a 1 MiB, medido novamente em UTF-8 antes do processamento;
JSON é estrito; YAML fica limitado a um único documento comum e seguro;
avisos precisam aparecer quando uma conversão pode perder informação da origem;
o analytics pode receber apenas um envelope permitido de operação e resultado, nunca o conteúdo do documento;
o produto precisa funcionar em inglês e português do Brasil, em layouts para desktop, tablet e celular.

Essas restrições mantiveram o primeiro produto pequeno. Também fizeram da privacidade, do comportamento do parser e da verificação de entrega partes do produto, e não um acabamento posterior.

Arquitetura

O Rails 8.1 fornece o shell renderizado no servidor, as rotas públicas, os metadados das páginas, o texto sobre privacidade e o endpoint de saúde /up. O Turbo cuida da navegação e o Stimulus gerencia o ciclo de vida da página. O TypeScript, empacotado com esbuild, concentra o comportamento do navegador e o protocolo do worker. Tailwind CSS 4 e Propshaft cuidam dos estilos e assets.

O Web Worker em TypeScript é a fronteira de processamento. Ele valida a operação solicitada e o tamanho da entrada, analisa o documento e devolve uma resposta estruturada limitada com estado de sucesso, aviso ou erro. O worker não lê DOM, armazenamento, cookies ou estado de rede. Ele também ignora respostas antigas depois de um reset ou de uma navegação, para que um cálculo anterior não substitua o estado mais novo da página.

A camada Rails permanece como shell, não como back-end de processamento de dados. Não há banco de dados da aplicação para migrar, fazer backup ou envolver no tratamento dos documentos. Cópia e download usam APIs do navegador, e o documento atual permanece na memória do navegador.

Limite de privacidade

A promessa de privacidade aparece na interface e é aplicada pelos contratos:

entrada, saída, diagnósticos e avisos ficam na sessão atual do navegador;
o worker não busca, envia, armazena nem encaminha o documento;
a aplicação não persiste o documento nem cria uma área de trabalho salva;
preferências de tema e idioma são os únicos valores que podem permanecer no armazenamento local;
a política de segurança de conteúdo restringe scripts, conexões, workers e frames.

O resultado é uma ferramenta local no navegador, não um serviço hospedado de processamento de documentos. Se o analytics opcional estiver bloqueado ou indisponível, a ferramenta continua funcionando.

Decisões do parser e de fidelidade

O Formatloom trata JSON como JSON estrito. Rejeita entrada vazia, sintaxe inválida, comentários e vírgulas finais em vez de aceitar silenciosamente um dialeto que a saída talvez não preserve.

O YAML é deliberadamente mais restrito: um único documento comum e seguro. O caminho de conversão mostra diagnósticos do parser e avisa sobre comentários, âncoras, aliases, chaves duplicadas, ordenação, números que podem perder precisão e outros recursos que talvez não sobrevivam à conversão para JSON.

Um aviso ainda retorna uma saída utilizável. Um erro mantém a entrada original disponível para correção. Essa distinção dá à pessoa a chance de inspecionar o trade-off, em vez de confundir um parsing bem-sucedido com uma conversão fiel.

Testes e verificação

O repositório registra especificações e contratos de produto para o worker, o modelo de dados, a interface e o envelope de analytics antes dos detalhes da implementação.

As verificações automatizadas cobrem comportamento do parser, avisos de fidelidade do YAML, validação do worker, requisições antigas, filtragem de analytics, temas e localização. Os testes do Rails cobrem os limites de rota e privacidade. Os testes de sistema no navegador exercitam o fluxo, o acesso por teclado, layouts responsivos, recarregamento, marca e requisições de rede. O CI também executa builds de assets, RuboCop, Brakeman e Bundler Audit.

O quickstart inclui uma verificação manual no painel Network: apenas assets estáticos e o host de analytics configurado devem receber requisições. Essa verificação importa porque um teste unitário aprovado, sozinho, não prova que o navegador não enviou o documento para outro lugar.

Acessibilidade

A acessibilidade faz parte do contrato da ferramenta. Os controles têm nomes acessíveis, o foco permanece visível, mudanças de estado são anunciadas, avisos são legíveis e navegáveis e o fluxo pode ser usado com teclado. O layout é verificado nas faixas de desktop, tablet e celular e continua utilizável sem uma tela larga.

As mesmas restrições que protegem os dados também orientam a interface: a pessoa precisa entender onde o processamento ocorre, o que o resultado significa e o que um aviso pede que ela revise.

Limite do analytics

O Umami é telemetria operacional opcional, não um segundo caminho de processamento. Os eventos podem descrever operação e resultado, como sucesso, aviso ou erro, cópia ou download. O adaptador valida uma lista permitida e exclui entrada, saída, nomes de documentos, hashes de conteúdo, tamanhos em bytes, gravações de sessão, identificadores de usuário e tokens locais de correlação.

O contrato de analytics é intencionalmente pequeno. Bloquear o script não pode mudar uma transição de estado da ferramenta, e diagnósticos e mensagens de aviso continuam locais.

Implantação Docker e Dokploy

A aplicação de produção é empacotada em uma imagem Docker com múltiplos estágios. A imagem compila os assets do navegador, inicia Thruster e Puma e executa com um usuário que não é root. A aplicação expõe /up como endpoint de saúde e não precisa de um serviço de banco de dados.

O serviço live está em formatloom.mirtilo.io, em um VPS gerenciado pelo Dokploy. A imagem é publicada no GitHub Container Registry e implantada atrás de um proxy HTTPS. O repositório também contém uma configuração Kamal para a mesma estrutura Docker/VPS; a implantação ativa usa Dokploy.

Essa estrutura pequena é intencional: um container da aplicação, nenhum serviço separado para processamento de documentos e nenhum banco de dados da aplicação. A fronteira operacional permanece proporcional ao produto.

Limitações e próximas decisões

O Formatloom não tem contas, áreas de trabalho salvas, processamento em lote, API pública de processamento ou recursos para equipes. O produto é gratuito. Conversão de JSON para CSV e diff estruturado são possíveis direções futuras, mas são hipóteses, não escopo comprometido.

Não há aqui evidência de número de usuários, receita, impacto em clientes, gestão de incidentes em alta escala, SLOs, observabilidade avançada ou exercícios executados de rollback em produção. Essas alegações precisam de registros próprios e não serão inferidas de uma URL funcionando ou de uma suíte de testes verde.

A próxima decisão deve ser guiada pela demanda: manter a fronteira estável, observar uso e evidências de entrega verificáveis e só adicionar um fluxo que justifique seu novo custo de privacidade e manutenção.