# 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

```text
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.