Frontend
React 19
A interface é uma aplicação React single-page. O app principal coordena geração do glossário, exportações, estado do menu, alertas e o fluxo de expansão termo por termo dentro de um único app no navegador.
Stack principal
O que é usado neste projeto e qual responsabilidade cada camada assume.
Linguagem
TypeScript
O código de runtime é escrito em TypeScript, tanto no frontend quanto nos handlers serverless. Os tipos ajudam a estruturar objetos do glossário, payloads dos termos, traduções e respostas de API.
Ferramenta de build
Vite 7
Vite alimenta o servidor de desenvolvimento e a build de produção do frontend. O projeto também usa o plugin React do Vite, o que o coloca no grupo de apps React modernos, e não de sites em Next.js ou Astro.
Regras do Glossário
Regras de qualidade dedicadas
Um conjunto completo de regras embutidas nos prompts do LLM que governam todos os aspectos da qualidade do glossário: seleção hierárquica de termos (fundamental → central → aplicado), estrutura de definição em duas frases (O QUE + POR QUE) com formato especial para siglas, pontuação de importância, consistência bidirecional de relações e regras de expansão Saiba Mais com explicações e fontes citadas. As regras são independentes de domínio — aplicam-se a qualquer assunto (tecnologia, ciência, humanidades, negócios), com a área da palavra-semente inferida automaticamente.
Integração com IA
Camada de LLM independente de provedor
A geração e expansão dos termos passam por uma abstração compartilhada de LLM. Gemini 2.5 Flash é o provedor padrão (o mais rápido para JSON estruturado, com qualidade semelhante), DeepSeek fica disponível pelo mesmo caminho compatível com OpenAI, e Anthropic (Claude Sonnet) fica disponível quando selecionado explicitamente.
Padrão de backend
Funções serverless da Vercel
O backend vive em api/ como funções TypeScript. Esses endpoints constroem prompts, chamam o modelo, limpam o JSON, validam o conteúdo e devolvem respostas ao navegador.
Como roda
O fluxo principal desde a palavra-semente até o glossário gerado.
1
React inicializa dentro do Vite
src/main.tsx monta o app React e o envolve com um provider de idioma. Vite serve o frontend em desenvolvimento e gera o bundle estático em produção.
2
O app carrega dados salvos do navegador
Ao iniciar, a aplicação lê qualquer glossário salvo em localStorage e restaura a última sessão. O idioma da interface também é persistido e reidratado a partir do navegador.
3
O frontend chama endpoints serverless
Quando o usuário gera um glossário ou expande um termo, o frontend envia JSON para /api/generate ou /api/expand por utilitários em src/utils/llmApi.ts.
4
O backend chama o LLM configurado, valida e normaliza o retorno
As funções serverless constroem o prompt, enviam a chamada pelo provedor configurado em LLM_PROVIDER, limpam problemas comuns de formatação e fazem o parse do JSON. A geração então executa uma normalização determinística em código — removendo termos duplicados, forçando a palavra-semente em primeiro lugar com importância 10, limitando as pontuações de importância e descartando relações que apontem para termos inexistentes ou para o próprio termo — antes de devolver os dados ao frontend.
5
React renderiza e exporta o glossário
O app mostra os termos, permite reexpansões, salva o trabalho localmente e exporta o resultado final em markdown ou DOCX.
Mapa da arquitetura
O projeto se divide entre um frontend React e um backend pequeno, porém especializado, para IA.
Pastas e arquivos principais
src/Aplicação React, provider de idioma, componentes e utilitários no cliente.
api/Funções serverless para gerar glossários e expandir termos.
public/Assets estáticos como ícones e favicon.
dist/Saída de build frontend após o passo de produção.
todo/Referências, notas de produto e documentação auxiliar do projeto.
.vercel/Metadados locais da Vercel para deploy e ferramentas de desenvolvimento.
src/content/GLOSSARY_RULES.mdRegras de qualidade do glossário que documentam a lógica dos prompts do LLM: seleção de termos, formato das definições, pontuação de importância, consistência entre relações e regras de expansão do Saiba Mais.
Análise da Arquitetura
package.json vite.config.ts tsconfig.json src/main.tsx src/App.tsx src/index.css src/utils/llmApi.ts src/utils/storage.ts src/i18n/LanguageContext.tsx api/_llm.ts api/_auth.ts api/_validation.ts api/generate.ts api/expand.ts src/content/GLOSSARY_RULES.md
A forma aqui é diferente do Card Tracker: não é um app Node orientado por arquivos com route handlers dentro de um framework. É um frontend Vite mais uma pasta api/ separada para a lógica de backend serverless.
Dados e armazenamento
A história de persistência é orientada pelo navegador, e não por um banco de dados.
Armazenamento no navegador
localStorage é a camada de persistência
O app salva o glossário gerado em localStorage automaticamente.
Os detalhes de termos expandidos também são cacheados em localStorage para reabertura rápida.
A preferência de idioma também é persistida no navegador.
Este projeto não depende de um banco de dados em uso normal.
Saídas geradas
As exportações acontecem no navegador
O export em markdown é criado no navegador como um blob para download.
O export em Word é montado no navegador usando o pacote docx .
O file-saver é usado para baixar o DOCX gerado.
O app é desenhado em torno de um estado de trabalho temporário e arquivos exportáveis.
Camada de IA e API
A maior parte da complexidade deste projeto está no design dos prompts, na seleção de provedor e no formato das respostas.
Endpoint de geração
/api/generate
Esse endpoint pede ao LLM configurado para detectar o idioma da palavra-semente, retornar rótulos traduzidos quando necessário, criar uma descrição do glossário e gerar exatamente 12 termos estruturados com definições e termos relacionados em JSON.
Endpoint de expansão
/api/expand
Esse endpoint pede ao LLM configurado parágrafos explicativos mais profundos e fontes confiáveis e apropriadas ao domínio para um único termo do glossário — documentação oficial e padrões para tecnologia, artigos revisados por pares e órgãos científicos para ciência, fontes primárias para humanidades. A resposta é mantida focada, estruturada e orientada por fontes para o recurso de Saiba Mais.
Comandos para rodar
Os comandos práticos e o ambiente esperado para trabalhar no projeto.
Scripts e modos locais de execução
npm install vercel dev npm run dev npm run build npm run preview npm run lint
A nuance importante é que vercel dev é o modo local full-stack de verdade, porque roda o frontend Vite e as funções serverless juntos. npm run dev é útil para trabalho focado só no frontend.
Ambiente esperado
O que o app precisa
LLM_PROVIDER seleciona o provedor: gemini por padrão, deepseek ou anthropic.
GEMINI_API_KEY é necessária para o provedor padrão. DEEPSEEK_API_KEY ou ANTHROPIC_API_KEY podem ser usadas quando esses provedores forem selecionados.
Node.js 18 ou superior é esperado pela documentação do projeto.
Vercel CLI faz parte do fluxo local recomendado.
Não há banco de dados para configurar. Os endpoints de API são protegidos por um segredo compartilhado (API_SECRET no servidor, VITE_API_SECRET no frontend), além de checagem de mesma origem e sanitização de entrada.
Resumo final
Glossary Builder é uma aplicação Vite + React + TypeScript com um pequeno backend serverless na Vercel. O valor central vem da geração com LLM configurável por provedor, enquanto o navegador cuida de estado, persistência local e exportação. Comparado com o Card Tracker, ele é mais um app frontend assistido por IA do que uma aplicação Node orientada por arquivos.