⚖️ Judge Pole - Manual de Usuario y Arquitectura

Judge Pole es una aplicación web serverless, ligera y portátil diseñada para arbitrar y evaluar proyectos durante "vibe coding" jams, hackathons y competiciones de desarrollo.

---

🚀 1. Filosofía y Arquitectura Técnica

• Cero Infraestructura: No requiere backend, bases de datos SQL/NoSQL ni servicios en la nube.
• Persistencia Portátil (Base64): Todo el estado de la aplicación reside en /Public/data/database.ecma.js codificado en una cadena Base64 que contiene un JSON plano.
• Construcción DOM Nativa: Construida íntegramente con Vanilla JS mediante el helper judge_pole.html(), evitando frameworks pesados y virtual DOMs.
• Sistema de Virtual DPI (Grid de 40 celdas): El diseño escala de manera uniforme adaptando la unidad base em al tamaño de la pantalla mediante un cálculo dinámico de fontSize.
• Internacionalización Dinámica: Soporte reactivo multilingüe basado en atributos data-i18n y data-i18n-without="true".

---

📁 2. Estructura del Proyecto

judge-pole/
├── Dockerfile                  # Entorno de compilación SASS
├── build.sh / build.bat        # Scripts de compilación de estilos
└── Public/
    ├── index.html              # Punto de entrada HTML
    ├── data/
    │   └── database.ecma.js    # Archivo físico de la BDD en Base64
    └── ecma/
        ├── Application/
        │   └── JudgePole.ecma.js       # Orquestador del ciclo de vida y UI
        ├── Managers/
        │   ├── DatabaseManager.ecma.js # Operaciones CRUD y serialización
        │   ├── I18NManager.ecma.js     # Motor de traducción
        │   ├── SessionManager.ecma.js  # Control de acceso y roles
        │   └── SettingsManager.ecma.js # Ajustes de visualización y FPS
        ├── Models/                     # Definiciones de datos
        ├── Utils/
        │   ├── Common.ecma.js          # Inyección de estilos y helpers
        │   ├── I18N.ecma.js            # Diccionarios de idiomas
        │   └── Styles.ecma.js          # Estilos SCSS en JavaScript
        └── Views/
            ├── UsersView.ecma.js       # Gestión y filtrado de jueces/creadores
            ├── ProjectsView.ecma.js    # Gestión y autoría de proyectos
            └── VotesView.ecma.js       # Matriz de notas ponderada y ranking

---

👥 3. Gestión de Participantes (Usuarios)

La vista de Usuarios permite registrar tanto jueces como participantes:

• Tipos de Usuario:

• Humano (👤): Por defecto.

• Inteligencia Artificial (🤖): Modelos LLM o agentes participantes.

• Avatar Adaptativo: Si no se define una URL o ruta local, se genera automáticamente un placeholder centrado con las iniciales o el icono de tipo.

• Buscador Reactivo: Filtra en tiempo real por nick, biografía o plataformas vinculadas.

• Seguridad / Contraseña:

• Puedes definir una contraseña opcional en cualquier participante.

• En cuanto al menos un usuario tenga contraseña, la web bloqueará la edición pública.

---

📦 4. Gestión de Proyectos

La vista de Proyectos permite administrar los trabajos presentados a la Jam:

• Coautoría Múltiple: Los proyectos pueden pertenecer a uno o varios creadores simultáneamente (equipos humanos, equipos de IAs o formatos híbridos).
• Selector con Scroll y Filtro: Al crear o editar un proyecto, la lista de autores cuenta con un buscador en vivo y altura restringida para no desbordar el formulario.
• Metadatos y Enlaces: Soporta etiquetas (#tags), tecnologías utilizadas y enlaces externos (repositorios, demos, webs).

---

⚖️ 5. Tribunal de Evaluación y Ranking

La vista de Votaciones es el núcleo de la aplicación:

5.1. Ranking en Vivo

• Posición Doble: Muestra la posición Global (absoluta en la Jam) y la posición en el Filtro (según la búsqueda tecleada).
• Criterio de Orden: Ordenado oficialmente por la Media Ponderada.
• Acordeón Desplegable: Al hacer clic sobre cualquier fila del ranking, se despliegan:
• El resumen de medias naturales y ponderadas de cada criterio.
• La Matriz Completa de Solo Lectura, visible para cualquier visitante.

5.2. Matriz de Puntuaciones Transpuesta

Al pulsar en "+ Registrar Votación" o al Editar (✏️):

• Estructura Transpuesta:

• Filas (Tuplas): Criterios de evaluación.

• Columnas: Jueces participantes.

• Columnas Finales: Media Natural y Media Ponderada por Criterio.

• Filas Inferiores (tfoot): Media Natural y Media Ponderada por Juez.

• Esquina Inferior Derecha: Media Global Doblemente Ponderada.

• Cálculo de Pesos (Weights):

• Tanto jueces como criterios admiten un Peso entero (por defecto 20, mínimo 1).

• Las medias se recalculan automáticamente en el cliente a medida que se teclean notas o se modifican los pesos.

• Gestión de Criterios en Caliente:

• Es posible añadir nuevos criterios con + Nuevo Criterio.

• Los criterios existentes pueden renombrarse (✏️) o eliminarse (✕), propagándose el cambio en cascada sobre todas las notas históricas guardadas.

---

🔐 6. Control de Acceso (Modo Admin vs. Público)

El sistema opera bajo dos estados dinámicos gestionados por SessionManager:

1. Modo Libre / Desarrollo:

• Si ningún usuario de la base de datos tiene contraseña asignada, la web asume que estás en local y muestra todas las opciones administrativas (+ Añadir, ✏️ Editar, ✕ Borrar, exportar Base64).

2. Modo Protegido (Visitante):

• Se activa en cuanto un usuario recibe una contraseña.
• La interfaz oculta todos los botones de creación, modificación y borrado.
• La cabecera muestra el botón "Acceder 🔐".
• Al iniciar sesión con nick y clave, la sesión pasa a ser administradora y se restauran todos los botones de control. Al pulsar "Salir 🚪", vuelve al modo protegido.

---

💾 7. Flujo de Guardado y Persistencia

Al ser una aplicación sin servidor backend, los cambios realizados en el navegador se almacenan en la memoria local activa. Para hacerlos permanentes:

1. Inicia sesión como administrador.
2. Pulsa en el botón "Base64 DB" en la barra superior.
3. Copia el contenido generado (const database = "...";).
4. Abre el archivo /Public/data/database.ecma.js en tu editor y sobreescribe su contenido.
5. Haz commit o despliega los cambios en tu servidor estático (GitHub Pages, Vercel, Netlify o servidor local).