Beacon — dashboard web local

Beacon es la SPA React 19 que viene embebida dentro del binario korva-vault. Visita localhost:7437 mientras el vault está corriendo para explorar observaciones, gestionar sesiones, editar scrolls, administrar equipos y audit log — todo sin salir nunca de tu máquina.

Actualizado: 2026-04-30

Beacon es el dashboard web local de tu Vault. Es una single-page application construida con React 19 + Vite 6 + Tailwind 4 + TypeScript 5.8, embebida dentro del binario korva-vault al momento del release (-tags embedui). Visita http://localhost:7437 mientras el vault está corriendo y ahí está — sin puerto extra, sin proceso extra.

Arquitectura

El mismo binario korva-vault sirve:

MCP sobre stdio (para clientes de IA).
API REST en /api/v1/* (para la CLI y tooling externo).
La SPA en / y cualquier ruta anidada (con fallback de routing SPA correcto a index.html).

En modo dev (npm run dev en beacon/), la SPA corre en el puerto 5173 y hace proxy de las llamadas a la API hacia http://localhost:7437/vault-api/*. Los builds de producción cocinan la SPA dentro del binario, así que no hay nada extra que desplegar.

Rutas

/                         → Landing de marketing (pública)
/admin/*                  → Panel admin (requiere admin.key)
  /admin/dashboard        → KPIs del sistema
  /admin/vault            → Vault Browser (búsqueda + delete)
  /admin/scrolls          → Scrolls públicos
  /admin/scrolls-private  → Scrolls privados (Teams+)
  /admin/teams            → Teams + miembros + invitaciones (Teams+)
  /admin/skills           → Skills Hub con versionado (Teams+)
  /admin/audit            → Audit log (Teams+)
  /admin/code-health      → Quality gates de SDD
  /admin/license          → Activación / status

/app/*                    → Dashboard de usuario
  /app/overview           → Stats del Vault
  /app/vault              → Vault Explorer (búsqueda de observaciones)
  /app/sessions           → Historial de sesiones
  /app/lore               → Lore Manager
  /app/settings           → Preferencias

Autenticación

El login del panel admin (/admin) ofrece dos métodos de autenticación — alterna entre ellos con el tab en la parte superior del formulario:

Tab	Quién lo usa	Credencial
Admin Key	Propietario del vault / setup inicial	Está en `~/.korva/admin.key` → copia el campo `key`
Session Token	Miembros del equipo con `role=admin`	Obtenido vía `korva auth redeem <invite-token>`, guardado en `~/.korva/session.token`

Ambas credenciales se validan contra el vault y se almacenan solo en sessionStorage (se borran al cerrar la pestaña). Máximo 5 intentos fallidos, lockout de 30 segundos al sexto.

Despliegues compartidos del vault — cuando ejecutas una única instancia de korva-vault para todo el equipo (p. ej. vault.tuempresa.com), solo la persona que configuró el servidor tiene la admin key. Cualquier otro admin del equipo puede acceder al panel haciendo login con su session token — sin necesidad de compartir la clave del servidor.

Gate de Teams — <TeamsGate> envuelve features solo para Teams y verifica useLicenseStatus().tier.

i18n

Beacon trae soporte completo en inglés y español: navegación, palabras comunes, flujos de auth, licencia, dashboard, vault, scrolls, scrolls privados, teams, skills, audit, code health, editor, glosario. Hook: useI18n() expone { lang, setLang, t, editor, setEditor }. Persistido en localStorage (korva-lang, korva-editor).

Stack

Concern	Elección
Framework	React 19 + react-router 7
Server state	TanStack Query 5 (con polling en el dashboard live)
Auth state	Zustand 5 con persistencia en sessionStorage
Iconos	lucide-react
Build / dev	Vite 6, Tailwind 4 (`@tailwindcss/vite`), TypeScript 5.8
Lint / format	Biome 1.9 (herramienta única que reemplaza ESLint + Prettier)
Tests	Vitest 3.2 + Testing Library + jsdom

Sistema de diseño

Token	Hex
`--bg`	`#060608`
`--surface`	`#0D1117`
`--surface-2`	`#161B22`
`--border`	`#21262D`
`--text`	`#E6EDF3`
`--accent`	`#22C55E`
`--red`	`#F85149` (errores)
`--blue`	`#388BFD` (enlaces)
`--orange`	`#D29922` (warnings)
`--purple`	`#A371F7` (informativo)

Tipografía: Syne (display), IBM Plex Sans (body), JetBrains Mono / Fira Code (código).

Compilar Beacon tú mismo

make beacon-dev          # servidor dev de Vite en :5173
make beacon-build        # build prod completo → beacon/dist
make vault-full          # build de Beacon + build Go con -tags embedui

El target vault-full es lo que release engineering corre para producir el binario que se distribuye.

Tests

7+ archivos de test en beacon/src/__tests__/:

AdminLogin.test.tsx — render, submit, validación, lockout
ErrorBoundary.test.tsx, Glossary.test.tsx, InfoCallout.test.tsx, PageHeader.test.tsx
adminStore.test.ts — mutaciones de Zustand + persistencia
i18n.test.ts — cambio de idioma + completitud de traducciones

Reporte de cobertura: v8 (--coverage), output HTML + texto.

¿Por qué un dashboard local?

La CLI es rápida para power users; Beacon es para el resto del equipo. Escribir scrolls, navegar el timeline, canjear invitaciones, gestionar skills — todo es más fácil en una UI. Y, lo más importante, como Beacon viene dentro del binario, no necesitas un despliegue separado para exponerlo.

Self-hosting — cuando quieres que Beacon sea alcanzable por el resto del equipo
Administración de Teams — features Teams del Beacon