feat: add architectural documentation for refactor; include audit, migration plan, rules, target architecture, and session handoff

2026-06-06 03:32:06 +00:00 · 2026-05-23 20:48:31 +02:00
parent 8c270feb5b
commit 225b2b36a2
5 changed files with 665 additions and 0 deletions
@@ -0,0 +1,203 @@
+# 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.
+