Responsabilidades

Duas colunas importam aqui. A coluna "possui" é o que você modifica quando está trabalhando numa feature daquela área. A coluna "não deve possuir" é o que manter de fora. Quando uma mudança puxa algo da coluna direita, é sinal de que a mudança quer outro lar.

Por que cada regra

domain.ts não deve possuir chamadas de SDK ou IO

Tipos de domínio são importados por todos os outros arquivos. Se eles puxam QVAC ou o sistema de arquivos, a direção das dependências inverte e o grafo inteiro vira circular. Mantém esse arquivo puro.

files.ts não deve possuir busca RAG ou completion

O adaptador de arquivos só produz LocalDocument[]. Chunking e embedding acontecem depois, em rag.ts e qvac.ts. Se você sentir vontade de embedar durante a descoberta de arquivos — digamos, para deduplicar — resista. Adiciona um passo separado.

rag.ts não deve possuir ciclo de vida do modelo

rag.ts chama ragChunk, mas não carrega modelos. O gateway QVAC cuida disso. Troca de modelos e qvac.ts muda uma vez. rag.ts continua funcionando.

qvac.ts não deve possuir UI ou caminhada por pastas

O gateway é sua única fonte de verdade para "o que o QVAC faz?". Não lê pastas, renderiza mensagens ou sabe sobre HTTP. É por isso que a superfície de cinco chamadas cabe na sua cabeça.

store.ts não deve possuir chamadas de modelo

O JSON store é para quais brains existem e quais chunks eles têm. Nunca embeda, busca ou completa. Quando um brain é apagado, store.ts remove a entrada. A classe de workflow trata o lado QVAC.

locallens.ts não deve possuir HTTP ou código de DOM

LocalLensApp é a classe de workflow. A CLI chama, o servidor chama, e a UI chama transitivamente. Nenhum deles deve vazar suas preocupações para essa classe. Se request.headers aparecer aqui, alguma coisa está errada.

cli.ts não deve possuir internos de RAG

A CLI é um dos dois pontos de entrada finos sobre o LocalLensApp. Ela sabe sobre argv e console.log. Não sabe sobre tamanho de chunk, embeddings ou prompts. Uma flag que mudaria comportamento de RAG pertence à camada de workflow, não ao handler da CLI.

server.ts não deve possuir lógica de negócio

Mesmo formato que a CLI: fino. O servidor é route-matching, parsing de JSON e mapeamento de erros. No momento em que você se pega escrevendo lógica ramificada num route handler, pertence ao LocalLensApp em vez disso.

ui/ não deve possuir chamadas QVAC

O navegador não consegue falar com o QVAC diretamente de qualquer jeito, mas a regra ainda importa: a UI conversa só com a API JSON do servidor. Não duplica constantes de tamanho de chunk, nomes de modelo ou IDs de workspace.

Dois pontos de entrada, um core

Repara que a CLI e o servidor são ambos finos. Eles ficam sobre o mesmo core (LocalLensApp) e oferecem superfícies diferentes. É por isso que adicionar uma feature à camada de workflow beneficia os dois — a CLI ganha no momento em que a rota do servidor ganha.