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

2026-06-06 03:32:06 +00:00 · 2026-06-04 17:07:01 +02:00
parent 8c270feb5b
commit 71c18b479b
5 changed files with 221 additions and 0 deletions
@@ -0,0 +1,53 @@
+# 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.