# 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

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

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