Responsabilidades

Dos columnas importan acá. La columna "posee" es lo que modificas cuando trabajas en una feature en esa área. La columna "no debería poseer" es lo que hay que mantener afuera. Cuando un cambio trae algo de la columna derecha, eso es una señal de que el cambio quiere otro hogar.

Por qué cada regla

domain.ts no debería poseer llamadas al SDK o IO

Los tipos de dominio los importan todos los otros archivos. Si echan mano a QVAC o al filesystem, la dirección de dependencias se invierte y el grafo entero se vuelve circular. Mantén este archivo puro.

files.ts no debería poseer búsqueda RAG o completion

El adaptador de archivos solo produce LocalDocument[]. El chunking y el embedding pasan después, en rag.ts y qvac.ts. Si alguna vez sientes el tirón de embeddear durante el descubrimiento de archivos — digamos, para deduplicar — resístelo. Agrega un paso separado.

rag.ts no debería poseer lifecycle del modelo

rag.ts llama a ragChunk, pero no carga modelos. El gateway de QVAC maneja eso. Cambia los modelos y qvac.ts cambia una sola vez. rag.ts sigue funcionando.

qvac.ts no debería poseer UI o recorrido de carpetas

El gateway es tu única fuente de verdad para "¿qué hace QVAC?". No lee carpetas, no renderiza mensajes, no sabe de HTTP. Por eso la superficie de cinco llamadas cabe en tu cabeza.

store.ts no debería poseer llamadas al modelo

El store JSON es para qué cerebros existen y qué chunks tienen. Nunca embeddea, busca ni completa. Cuando un cerebro se borra, store.ts remueve la entrada. La clase del workflow maneja el lado de QVAC.

locallens.ts no debería poseer HTTP o código DOM

LocalLensApp es la clase del workflow. La CLI la llama, el servidor la llama y la UI la llama transitivamente. Ninguno debería filtrar sus preocupaciones a esta clase. Si request.headers alguna vez aparece acá, algo está mal.

cli.ts no debería poseer internas de RAG

La CLI es uno de dos puntos de entrada delgados sobre LocalLensApp. Sabe sobre argv y console.log. No sabe sobre tamaños de chunk, embeddings o prompts. Un flag que cambiaría el comportamiento del RAG pertenece a la capa del workflow, no al handler de la CLI.

server.ts no debería poseer lógica de negocio

Misma forma que la CLI: delgado. El servidor es route-matching, parsing de JSON y mapeo de errores. En el momento que te encuentras escribiendo lógica con ramas en un route handler, pertenece a LocalLensApp.

ui/ no debería poseer llamadas a QVAC

El navegador no puede hablar con QVAC directamente de todas formas, pero la regla igual importa: la UI solo habla con la API JSON del servidor. No duplica constantes de tamaño de chunk, nombres de modelos ni IDs de workspace.

Dos puntos de entrada, un core

Nota que la CLI y el servidor son ambos delgados. Se asientan sobre el mismo core (LocalLensApp) y proveen superficies distintas. Por eso agregar una feature a la capa del workflow beneficia a los dos — la CLI la recibe en el momento que la ruta del servidor la tiene.