scoreko-dev/docs/refactor/TARGET_ARCHITECTURE.md

Target Architecture

Este documento es la source of truth para la arquitectura objetivo del refactor. Las futuras sesiones deben alinearse con esta estructura y con las reglas de ARCHITECTURE_RULES.md.

Objetivo

Crear una arquitectura simple y realista que:

• Centralice la frontera NodeCG.
• Centralice contratos realtime.
• Separe dominio puro de UI y runtime.
• Permita añadir providers, packs y skins sin duplicación.
• Preserve el comportamiento visual de overlays durante la migración.

Estructura Objetivo

src/
  shared/
    schemas/
    types/
    domain/
      scoreboard/
      players/
      commentary/
      packs/
      integrations/
    utils/
  nodecg/
    browser/
      replicants.ts
      messages.ts
    extension/
      context.ts
      replicants.ts
      messages.ts
  extension/
    modules/
      packs/
      integrations/
        startgg/
        challonge/
      oauth/
  dashboard/
    app/
    features/
      scoreboard/
      players/
      graphics/
      settings/
      integrations/
      packs/
    stores/
    ui/
  graphics/
    shared/
      composables/
      view-models/
      assets/
    scoreboard/
    scoreboard-2xko/
    commentary/

Boundaries

Boundary	Puede hacer	No puede hacer
shared/domain	Tipos, funciones puras, normalizadores, mapping.	Importar Vue, NodeCG o DOM.
nodecg/browser	Acceso browser a replicants y messages.	Contener lógica de negocio o UI.
nodecg/extension	Acceso server a nodecg.Replicant, listenFor, mount y logging.	Implementar lógica específica de features.
dashboard/stores	Estado de aplicación y sync con replicants.	Contener UI compleja.
dashboard/features	Componentes y composables por feature.	Acceder directamente a NodeCG.
graphics/shared	View models, helpers visuales compartidos, assets compartidos.	Cambiar contratos realtime.
extension/modules	Handlers y servicios pequeños registrados desde bootstrap.	Mezclar responsabilidades sin separación.

Flujo Realtime Objetivo

schemas
  -> generated types
  -> nodecg/browser + nodecg/extension
  -> dashboard stores / extension modules / graphics view models

Reglas del flujo:

• Todo replicant persistente o realtime tiene schema.
• Los tipos se generan desde schemas.
• Dashboard y graphics no crean replicants directamente.
• Extension modules no exponen replicants sin pasar por nodecg/extension.

Replicants

Fuente de Verdad

Los schemas son la fuente de verdad para todos los replicants.

Replicants a Mantener

• scoreboard
• players
• commentary
• graphicsSettings

Replicants de Packs a Formalizar

• installedPacks
• packRegistry
• downloadStates
• availableUpdates

Replicants a Eliminar

• exampleReplicant

Messages

Los messages deben estar namespaced por dominio.

Dominio	Ejemplos
Packs	packs:fetchRegistry, packs:download
Start.gg	integrations:startgg:createOAuthSession
Challonge	integrations:challonge:createOAuthSession

Los componentes y composables de feature no deben llamar nodecg.sendMessage directamente. Deben usar clientes o services definidos en el boundary browser.

Shared Domain

shared/domain contiene lógica reusable sin runtime:

• scoreboard: normalización de estado, mapping de jugadores, derivaciones de marcador.
• players: normalizadores, import/export, validación ligera.
• commentary: estado y mapping de comentaristas.
• packs: manifests, registry, installed packs y derivaciones.
• integrations: tipos normalizados, parsing básico y modelos comunes.

Extension Modules

La extensión debe registrarse desde un bootstrap explícito y delegar en módulos:

Módulo	Responsabilidad
packs	Registry, downloads, disk store, static mount, replicant sync y handlers.
integrations/startgg	Cliente Start.gg, OAuth session polling y parsing.
integrations/challonge	Cliente Challonge, OAuth session polling y parsing.
oauth	Reuso de oauth-server.ts y flujos comunes OAuth.

Dashboard

El dashboard se organiza por features:

• scoreboard
• players
• graphics
• settings
• integrations
• packs

Las vistas coordinan features. Los componentes implementan UI. Los stores mantienen estado y sincronización.

Graphics

Los overlays deben leer estado mediante view models:

• useScoreboardOverlayViewModel
• useCommentaryOverlayViewModel

graphics/shared contiene:

• Composables visuales.
• View models.
• Helpers de flags.
• Helpers de score animation.
• Helpers de text fitting.
• Assets compartidos.

El layout visual existente se conserva hasta tener verificación visual estable.

Naming Canónico

Tipo	Convención	Ejemplo
Replicant	camelCase	graphicsSettings
Replicant constants	replicantNames	replicantNames.graphicsSettings
Message	<domain>:<action>	packs:download
Integration message	integrations:<provider>:<action>	integrations:startgg:createOAuthSession
Store	use<Feature>Store	usePlayersStore
Service	create<ServiceName>	createPackService
Provider client	create<Provider>Client	createStartggClient
Overlay view model	use<Overlay>OverlayViewModel	useScoreboardOverlayViewModel

Arquitectura a Preservar

• Pinia como estado del dashboard.
• Quasar como UI principal.
• Schemas JSON como fuente de tipos.
• syncStateWithReplicant como concepto.
• oauth-server.ts como base reusable.
• countries.ts como utilidad encapsulada.
• Layout visual de overlays hasta completar verificación visual.