scoreko-dev/docs/refactor/ARCHITECTURE_AUDIT.md

Architecture Audit

Este documento resume el estado arquitectónico actual de Scoreko y debe usarse como referencia para el refactor. No redefine la arquitectura objetivo; documenta el diagnóstico existente y los riesgos detectados.

Estado Actual

La repo es un bundle NodeCG con Vite, Vue 3, Quasar, Pinia y vite-plugin-nodecg.

Área	Ruta	Responsabilidad actual
Extension	src/extension	Lógica server NodeCG, OAuth, brackets y pack manager.
Dashboard	src/dashboard/scoreko-dev	App Quasar/Pinia para control.
Graphics	src/graphics	Overlays broadcast: scoreboard, scoreboard-2xko, commentary.
Browser shared	src/browser_shared/replicants.ts	Acceso browser a replicants.
Shared	src/shared	Tipos, utilidades, países, packs y personajes.
Schemas	schemas	Schemas de replicants principales.
Build outputs	dashboard, graphics, extension, shared/dist	Outputs ignorados por git.

Replicants

Declarados por Schema

• scoreboard
• players
• commentary
• graphicsSettings
• exampleReplicant

Declarados Solo en Código

• installedPacks
• packRegistry
• downloadStates
• availableUpdates

Problema Principal

El contrato realtime está dividido entre schemas y código runtime. Parte vive en schemas, y parte en pack-manager o usePackRegistry. Esto dificulta validar cambios, regenerar tipos y entender qué estado público existe realmente.

Flujo de Datos

1. El dashboard escribe en Pinia stores.
2. Los stores sincronizan con replicants mediante store-sync.ts.
3. Los overlays leen replicants directamente desde browser_shared/replicants.ts.
4. La extensión escucha mensajes NodeCG como startgg:*, challonge:* y downloadPack.
5. La extensión actualiza replicants o disco.
6. graphicsSettings.scoreboardSkin redirige entre overlays scoreboard y scoreboard-2xko.

Zonas Grandes o de Riesgo

Archivo	Riesgo
src/dashboard/scoreko-dev/views/Players.vue	Vista demasiado grande: tabla, CRUD, import/export, integraciones y dialogs.
src/dashboard/scoreko-dev/components/PlayerSidePanel.vue	UI duplicada para left/right.
src/dashboard/scoreko-dev/views/Settings.vue	Mezcla idioma, shortcuts, OAuth y tokens.
src/dashboard/scoreko-dev/composables/useIntegration.ts	Mezcla estado UI, localStorage, polling OAuth, importación y cleanup.
src/extension/pack-manager.ts	Mezcla config, tipos, FS, HTTP static, downloads, updates, replicants y handlers.
src/graphics/scoreboard/main.vue	Lógica, layout, animaciones, flags y CSS mezclados.
src/graphics/scoreboard-2xko/main.vue	Mismo riesgo que scoreboard/main.vue.

Hallazgos Técnicos

• No se detectaron ciclos de imports en los archivos TS/Vue revisados.
• Sí hay accesos frágiles al entorno NodeCG:
  • nodecg global en composables.
  • NodeCG.Replicant declarado manualmente.
  • Imports a package.json desde UI.
  • Tipos generados desalineados.
  • Acceso directo a replicants fuera de stores o servicios.

Problemas Reales

• La frontera NodeCG está rota: browser_shared/replicants.ts, stores, Graphics.vue, overlays y usePackRegistry acceden a NodeCG de formas distintas.
• Los contratos realtime no están centralizados.
• pack-manager.ts necesita reescritura controlada, no parcheo incremental.
• usePackRegistry.ts y fighting-characters.ts necesitan reescritura controlada.
• startgg.ts y challonge.ts duplican estructura: OAuth mode, proxy exchange, session polling API y parsing básico.
• Players.vue y Settings.vue son feature modules completos metidos en vistas.
• Los overlays son de alto riesgo visual y deben tocarse con mucho cuidado.
• Hay dead code claro: exampleReplicant, example.ts, ExampleType y schema de ejemplo.
• src/types/schemas/configschema.d.ts está stale: contiene exampleProperty, pero configschema.json ya no lo define.
• lint falla por _id en Players.vue y _config en startgg.ts y challonge.ts.
• El resto de lint son warnings de formato Vue.

Impacto a Medio y Largo Plazo

• Añadir providers o skins duplicará lógica.
• Contributors externos no sabrán dónde tocar: store, composable, replicant o extensión.
• Refactors visuales pueden romper overlays porque no hay separación entre view model y presentación.
• El sistema de packs es el mayor riesgo por acoplar descarga, estado realtime, manifests, FS y UI.

Zonas a Preservar

• La idea de syncStateWithReplicant.
• Stores scoreboard, players y commentary como base razonable.
• oauth-server.ts como pieza reusable.
• countries.ts, que está bien encapsulado.
• Schemas JSON como fuente de tipos.
• UI Quasar existente, preservando comportamiento visual mientras se divide.

Baseline de Checks

Check	Estado
vue-tsc	Pasa.
tsc	Pasa.
lint	Falla con 3 errores reales y 243 warnings de formato.