Por que essa estrutura

O LocalLens vive em oito arquivos TypeScript em src/. Oito não é um número mágico — é a menor divisão que dá a cada camada uma fronteira clara sem deixar nenhuma delas apertada.

Essa página explica por que não é um arquivo e por que não são trinta.

Por que não um arquivo

Uma versão de arquivo único do LocalLens é tentadora nesse tamanho. É errada também, por três razões:

1. Integração com QVAC não deve compartilhar arquivo com código de UI. O ciclo de vida do modelo tem preocupações próprias — carregamento lazy, seleção de fallback, cleanup de workspace. Passar isso por um handler de UI ou esconde ou duplica.
2. Adaptadores de arquivo não devem compartilhar arquivo com inferência de modelo. A caminhada por pasta e a normalização do file picker do navegador são independentes do passo de embedding. Manter separados deixa você mudar um sem tocar no outro.
3. Fronteiras visíveis ajudam leitores. Alguém avaliando a base de código ou considerando uma extensão pode ler só src/qvac.ts para aprender a superfície do QVAC, só src/files.ts para input, só src/locallens.ts para workflow. Um monolito força a segurar tudo na cabeça.

Por que não over-architected

O LocalLens deliberadamente não tem:

• uma hierarquia de pastas profunda (src/services/rag/qvac/embeddings/…);
• interfaces abstratas de repositório ou "store";
• um framework de injeção de dependência;
• uma abstração prematura de banco vetorial;
• um sistema de plugins;
• um pipeline de build customizado além de bun build.

Qualquer um desses seria razoável num app maior. Nenhum deles é gargalo nesse tamanho. Seriam só cerimônia que você teria que ler antes de chegar no código real.

O formato que ele tem

A próxima página expande isso com o que cada arquivo não deve possuir. Fronteiras são mais fáceis de defender quando você sabe o que está do outro lado delas.