scoreko-dev/docs/refactor/TARGET_ARCHITECTURE.md

Arquitectura Objetivo (Target Architecture)

Important

Este documento sirve como la única fuente de la verdad para el diseño del sistema durante y después del refactor.

Estructura de Capas

La aplicación se dividirá estrictamente en las siguientes capas lógicas:

1. Capa NodeCG (Bindings): Archivos cuya única responsabilidad es declarar nodecg.listenFor (backend) o importar nodecg.Replicant (frontend).
2. Capa de Estado (Stores): Pinia será la única fuente de la verdad para la UI. Los stores se hidratarán de los replicants sin lógicas cruzadas complejas de localStorage.
3. Capa de Lógica Pura (Services/Domain): Funciones en TypeScript puro sin dependencias de Vue ni de NodeCG que transforman, formatean o calculan datos.
4. Capa de UI (Dumb Components): Componentes Vue puramente presentacionales que solo reciben props y emiten events.
5. Capa de Orquestación (Smart Components / Composables): Vistas y composables que conectan los Stores y/o NodeCG con los Dumb Components.

Estructura de Carpetas Propuesta

src/
├── browser_shared/
│   ├── replicants.ts        # Declaraciones puras
│   └── useReplicant.ts      # (NUEVO) Composable unificado para hidratar Vue desde NodeCG
├── shared/
│   ├── types/               # Tipos estrictos compartidos
│   └── utils/               # Helpers de dominio puros (ej. formateo)
├── extension/               # Backend NodeCG
│   ├── index.ts             # Entry point
│   ├── nodecg-bindings/     # Registro exclusivo de nodecg.listenFor()
│   ├── services/            # Lógica de negocio pura (StartGGService, ChallongeService)
│   ├── api/                 # Llamadas HTTP/GraphQL
│   └── oauth/               # Manejo de flujos de autenticación OAuth aislados
├── dashboard/
│   └── scoreko-dev/
│       ├── components/      # UI (Small, dumb components)
│       ├── composables/     # Lógica orquestada y reutilizable
│       ├── features/        # (NUEVO) Dominio agrupado (ej. /players, /integrations)
│       ├── stores/          # Pinia stores (Fuente de la verdad UI)
│       └── views/           # Smart components (Orquestadores)
└── graphics/
    ├── shared/              # (NUEVO) Componentes y composables compartidos entre gráficos
    │   ├── directives/      # ej. v-fit-text
    │   └── composables/     # ej. useScoreAnimation, useFlags
    ├── scoreboard/
    │   ├── components/      # Componentes segregados (PlayerName.vue, Score.vue, BackgroundPanel.vue)
    │   └── App.vue          # Orquestador principal del scoreboard
    └── scoreboard-2xko/

Reglas Arquitectónicas de Diseño

• Domain Driven: El backend y el dashboard se organizarán por dominio o feature (players, scoreboard, integrations) donde sea posible.
• Aislamiento de NodeCG: En el backend, toda lógica debe vivir en clases o funciones de servicio que reciben datos y devuelven promesas. La integración con la API de NodeCG solo llama a esos servicios; no se debe inyectar NodeCG en los servicios si no es estrictamente necesario.
• Tipado Estricto: Todo el output de GraphQL/HTTP debe validarse/parsearse a un tipo de dominio lo antes posible en la capa de API.