Por que criei o Formatloom: uma ferramenta pequena com um limite claro

Por que o Formatloom existe

O Formatloom começou com uma pequena irritação: JSON e YAML são fáceis de ler até que um documento precise ser verificado, formatado ou convertido. A tarefa em si costuma ser rápida. A parte desconfortável aparece quando o documento contém dados de configuração ou de uma API e a ferramenta online mais rápida pede que você envie tudo para o servidor de outra pessoa. Eu queria que o documento permanecesse no navegador.

O Formatloom é o segundo pequeno serviço da Mirtilo IO depois do MaxBid. É uma ferramenta gratuita para formatar e validar JSON, converter JSON e YAML e explicar o que pode ser perdido durante a conversão. Mantive o fluxo restrito para poder levar um produto real do design à manutenção, passando por testes e implantação.

A V1 me dá algo para mostrar, uma oportunidade de aprender com o uso e uma forma de observar como o produto se comporta nas buscas. Também me permite trabalhar limites de produto, privacidade, acessibilidade, implantação e manutenção em um produto realmente gratuito. Áreas de trabalho salvas, processamento em lote, uma API e recursos para equipes são possíveis adições futuras. Quero que as decisões sobre esses recursos acompanhem a demanda, em vez de partirem de uma suposição feita antes do lançamento.

O design local no navegador

A exigência de processamento local no navegador definiu a aplicação. O Formatloom não tem sistema de contas, banco de dados da aplicação, área de trabalho salva, endpoint de upload ou API de processamento. O Rails renderiza o shell da aplicação e as páginas públicas. Um Web Worker em TypeScript processa o documento no navegador. Ele verifica a operação solicitada, recalcula o tamanho em UTF-8, aplica o limite de entrada de 1 MiB, analisa o documento e retorna um resultado limitado com diagnósticos ou avisos.

A stack técnica e suas decisões

A aplicação usa Ruby 3.4.6 e Rails 8.1 para o shell renderizado no servidor, as rotas, os metadados das páginas, o texto sobre privacidade e o endpoint de saúde. 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 dos assets. Em produção, uma imagem Docker com múltiplos estágios executa Thruster e Puma com um usuário que não é root. Não há banco de dados para configurar, migrar, fazer backup ou envolver no processamento dos documentos.

Cada parte da stack tem uma razão prática. O Rails mantém o shell e as páginas públicas na mesma aplicação, sem acrescentar outra fronteira de frontend para manter. O TypeScript coloca o parser, as mensagens do worker, os diagnósticos e os eventos de analytics sob o mesmo sistema de tipos. Mover o parser para um worker o mantém distante da interface principal, o que importa quando alguém abre um documento maior em um dispositivo mais lento. O resultado é uma aplicação pequena e fácil de acompanhar, respeitando a regra de privacidade.

Tornando a conversão de dados estruturados previsível

O processamento local precisa de limites claros. O Formatloom trata JSON como JSON estrito, então rejeita comentários, vírgulas finais, entrada vazia e sintaxe inválida. O YAML fica limitado a um único documento comum e seguro. O conversor avisa sobre comentários, âncoras, aliases, chaves duplicadas, ordenação, números que podem perder precisão e avisos do parser quando esses detalhes podem não sobreviver à passagem para JSON. Os avisos ainda produzem um resultado utilizável. Os erros mantêm a entrada original disponível para correção.

Essa distinção importa porque uma ferramenta de formatação pode alterar um documento enquanto parece estar apenas ajudando. O Formatloom torna esse risco visível. A pessoa pode copiar ou baixar o resultado e recebe um aviso quando a origem contém algo que o formato de destino não consegue representar fielmente.

Qualidade de engenharia em um produto pequeno

Uma view Rails compartilhada alimenta as rotas do formatador, do validador e de JSON/YAML. O Stimulus gerencia o ciclo de vida da página, o Turbo cuida da navegação e o worker permanece independente do DOM, do armazenamento, do analytics e das requisições de rede. A cópia e o download usam APIs do navegador. As preferências de tema e idioma são os únicos valores que podem permanecer no armazenamento local. A mesma interface oferece inglês e português do Brasil, além dos temas System, Light e Dark e de layouts para desktop, tablet e celular.

A privacidade faz parte da interface e do código. A ferramenta explica que o conteúdo gerado permanece local e que o Formatloom não o salva. O analytics opcional do Umami registra eventos como uma operação concluída, um erro, uma cópia ou um download. A lista de eventos permitidos contém apenas metadados da operação e do resultado. O serviço não recebe a entrada, a saída, nomes de documentos, hashes de conteúdo, tamanhos em bytes ou gravações de sessão. Se o serviço de analytics estiver bloqueado ou indisponível, a ferramenta continua funcionando.

Acessibilidade e consistência visual fizeram parte dos requisitos iniciais. O Formatloom segue a linguagem visual da Mirtilo IO e do MaxBid, mas mantém seus próprios assets e caminhos de implantação. A interface tem foco visível, controles identificados, mensagens de status ao vivo, acesso por teclado, estados de aviso legíveis e um layout que funciona sem uma tela larga. Esses detalhes determinam se alguém consegue usar o resultado com conforto e entender o que aconteceu.

Antes de considerar a implementação concluída, escrevi especificações e contratos de produto para o worker, a interface e o analytics. O controller do Rails aceita apenas modos de trabalho conhecidos. O worker valida a própria operação e o tamanho da entrada, retorna dados estruturados limitados e ignora respostas antigas depois de um reset ou de uma navegação. As mensagens derivadas do usuário são renderizadas como texto. A política de segurança de conteúdo restringe os destinos permitidos para scripts, conexões, workers e frames.

A suíte de testes segue os mesmos limites. Os testes de TypeScript cobrem o 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 exercitam o fluxo no navegador, o acesso por teclado, os layouts responsivos, o comportamento após recarregar, a marca e as requisições de rede. O CI também executa os builds de assets, RuboCop, Brakeman e Bundler Audit. É muita verificação para uma ferramenta pequena, mas isso torna as mudanças futuras mais seguras.

Usei IA durante partes da implementação e ao explorar decisões técnicas. A fronteira do produto veio de escrever o que o Formatloom nunca deveria precisar fazer. Depois que as regras de não fazer upload e não usar banco de dados ficaram explícitas, elas orientaram a arquitetura, o contrato do worker, o contrato de analytics, os testes, a política de segurança de conteúdo e o checklist de lançamento. A IA reduziu parte do trabalho de implementação. A revisão do código, os testes e a inspeção do produto em execução continuaram sendo necessários.

Implantação e hospedagem

O serviço em produção está em formatloom.mirtilo.io, em um VPS gerenciado pelo Dokploy. A aplicação é empacotada como uma imagem Docker de produção, e os assets do navegador são compilados durante a construção da imagem. A imagem é publicada no GitHub Container Registry e depois implantada pelo Dokploy atrás de um proxy HTTPS para o domínio público. O container inicia Thruster e Puma, executa com um usuário que não é root e expõe /up para monitoramento de saúde.

O repositório também inclui uma configuração de implantação do Kamal para a mesma estrutura baseada em Docker e VPS. A implantação ativa usa Dokploy. A estrutura de lançamento tem um container da aplicação, nenhum banco de dados da aplicação e nenhum serviço separado para processamento de documentos. Isso mantém o custo operacional proporcional ao produto e deixa espaço para adicionar infraestrutura quando as pessoas realmente precisarem dela.

Impacto e próximos passos

Para quem usa, o Formatloom é uma forma rápida de inspecionar dados estruturados sem enviá-los para um serviço de conversão. Para mim, é um exemplo real de levar um produto pequeno dos requisitos até a produção. O trabalho cobre design de interface, comportamento do parser, privacidade, acessibilidade, testes, empacotamento com Docker, implantação, analytics e descoberta em buscas. Todas essas preocupações aparecem quando a aplicação está rodando.

O Formatloom mudou a forma como penso no próximo produto da Mirtilo IO. JSON e YAML são a base de uma aplicação com fluxos relacionados. Conversão de JSON e CSV e diff estruturado são possíveis próximos passos, com cada recurso lançado e medido dentro do mesmo produto. O Formatloom continuará gratuito. Não haverá planos pagos nem bloqueio de funcionalidades, então as adições futuras serão avaliadas pela utilidade que trazem ao produto.

Uma lição foi que um produto implantado ainda precisa de evidências de lançamento, configuração de produção, verificações de analytics, validação responsiva e documentação. Uma URL respondendo é apenas um dos pontos de verificação do lançamento.

O Formatloom é gratuito, e eu acompanho operações concluídas, erros, cópias, downloads, retornos e o valor que ele acrescenta ao portfólio da Mirtilo IO. Essas observações ajudam a orientar quais melhorias construir em seguida, em vez de depender de um roadmap maior escrito de antemão.

Fontes

• Formatloom
• Mirtilo IO