Arquitectura del proyecto

Página de referencia técnica: cómo está construido Lumbre por dentro — las familias de contenido, los formatos internos (lumbre-lo/1.0 y sus hermanos), los tipos de bloque, la base de datos, la publicación y la API. No es una guía de uso: es el mapa del sistema.

La autoridad final de cada formato vive en el código: los validadores SchemaValidator, LabValidator, GameValidator, TourValidator, ShowValidator y AppValidator. Esta página describe ese contrato; si el código evoluciona, el código manda.

Las nueve familias del catálogo

Todo lo que existe en Lumbre es un destino de contenido registrado en App\Core\Content, la fuente de verdad compartida por «me gusta», «recomendar» y el descubrimiento:

• course — círculo (circles): la jerarquía escolar (categoría → grado → curso) es autorreferencial en esa misma tabla. URL /circles/{slug}.
• book — lectura o libro (books): incluye la lectura corta (content_type='short_read') y el cómic. URL /book/{slug}.
• object — Objeto de Aprendizaje (learning_objects): la lección interactiva en formato lumbre-lo/1.0. URL /object/{slug}.
• collection — ruta de aprendizaje (collections + collection_objects): una secuencia enlazada de objetos. URL /collections/{slug}.
• lab — laboratorio (labs, formato lumbre-lab/1.0): experimentos declarativos por componentes. URL /labs/{slug}.
• game — juego (games, formato lumbre-game/1.0): misiones de repaso gamificado. URL /games/{slug}.
• tour — recorrido (tours, formato lumbre-tour/1.0): paradas navegables con multimedia. URL /tours/{slug}.
• show — show (shows, formato lumbre-show/1.0): escenas con agentes, gestos y checks. URL /shows/{slug}.
• app — herramienta (apps, formato lumbre-app/1.0): micro app práctica cuyo paquete sólo nombra un motor ya aprobado e instalado (AppCatalog) y aporta su configuración y assets — nunca código del autor, para que un canal remoto no pueda convertirse en ejecución remota. URL /apps/{slug}.

Cada familia lleva estado (DRAFT/PENDING/PUBLISHED/REJECTED en objetos; published en experiencias) y visibilidad (PRIVATE/CIRCLE/UNLISTED/PUBLIC). Los candados de acceso no se reinventan: Content::canView() delega en el modelo nativo de cada tipo.

Objetos de aprendizaje: lumbre-lo/1.0

Un objeto es un documento JSON con tres claves raíz obligatorias y cuatro opcionales:

• format — siempre el literal "lumbre-lo/1.0".
• meta — título, autor, objetivo, descripción, materia, edades, idioma, tags, alignment (anclaje curricular SEP), skills (máximo 12) y discovery.
• blocks[] — secuencia ordenada de hasta 120 bloques mezclables: el cuerpo de la lección.
• reinforcements (opcional) — hasta 12 mini-lecciones de refuerzo, cada una con sus bloques.
• companion (opcional) — el tutor interactivo.
• world_connections (opcional) — conexiones del tema con el mundo.
• curriculum (opcional) — el fundamento oficial estructural: ancla el OA a requisitos reales de un plan de estudios (framework + requirements[] referenciados por su code estable). Al ser parte del documento, viaja en la sincronización maestro → esclavo y se re-materializa en el destino (por código, auto-proveyendo marco y requisito). Todo lo que declara un agente queda como agent_proposed; la página confirmada sólo se muestra si está verificada.

Regla dura del validador: sin claves desconocidas, enums cerrados, límites de longitud, y todo bloque con respuesta correcta (mcq, true_false, fill_blank, match, sort, sequence, numeric_answer, error_detective, confidence, prediction, text_highlight) debe llevar evidence citable.

Vocabulario de bloques

• Contenido: heading, text, list, callout, quote, link, scratchpad.
• Medios: image, figure (figura con caption obligatorio), audio, video, embed ( sólo youtube o vimeo, con lista blanca de id).
• Datos y gráficos: table, chart (bar, hbar, line, area, pie, donut, radar), graph (curvas expresadas con funciones como sin, cos, sqrt, log), formula (LaTeX-lite con operadores sum, prod, int, lim), mindmap, before_after, source_compare.
• Preguntas: mcq, true_false, fill_blank, match, sequence, numeric_answer, error_detective, confidence, prediction, text_highlight, reflection, argument_builder.
• Juegos de repaso: wordsearch, memory, sort, flashcards, timeline, branch (historia ramificada: grafo cerrado alcanzable desde start), step_reveal.
• Motor visual: visual_explanation — escenas declarativas (máximo 14) con items semánticos (text, number, emoji, shape, image, label, group) y actions (show, hide, highlight, move, pulse, wait). La IA describe qué explicar; el motor decide cómo componerlo.
• Continuidad: checkpoint — umbral passing_score (0–1), bloques puntuados covers, y destinos on_pass / on_fail.

Nada de esto es HTML del autor: los bloques son datos inertes y el runtime de Lumbre construye el tablero, las tarjetas o el gráfico.

Refuerzos y apoyos

• Refuerzos (reinforcements): viven dentro del objeto. Tipos: alternative_explanation, example, video, visual, step_by_step, prerequisite_review, analogy, practice, custom. Se presentan con etiquetas amables («Otra explicación», «Paso a paso», «Repasa esto primero»).
• Apoyos: objetos con slug apo-… que atacan una dificultad concreta. Dos vocabularios cerrados en App\Models\LearningObject: 11 tipos (explicamelo-facil, con-dibujos, paso-a-paso, ejemplos, detecta-el-error, truco, practica, reto, mini-examen, juego, antes-de-seguir) y 12 necesidades (explicar, bases, mates, leer, escribir, practicar, examen, tarea, ciencias, mundo, ingles, digital). El puente con el contenido curricular son las etiquetas tema: — match literal byte a byte, no círculo duplicado.
• Autoevaluación: banco propio (autoeval_questions, autoeval_sessions) con rutas /autoeval/{slug}; la zona de autoevaluación lee del banco, no del payload del objeto.

Experiencias: el patrón de los motores declarativos

Laboratorios, juegos, recorridos, shows y herramientas comparten la misma arquitectura declarativa:

• Catálogo de vocabulario cerrado (ComponentCatalog, ShowCatalog, …): componentes, agentes, gestos, fondos — nombrados, nunca programados.
• Validador estructural sin BD (LabValidator, GameValidator, TourValidator, ShowValidator, AppValidator): devuelve errores legibles pensados para que un agente los corrija y reintente.
• Renderizador: convierte la definición ya validada en el HTML de la experiencia; el paquete nunca trae código del autor.
• Publisher: ingesta idempotente por uid/slug con assets adjuntos.
• Las experiencias pueden declararse emparentadas entre sí (meta.relationships, tipos oa, lab, game, tour, show).

Base de datos

Tablas nucleares (esquema en database/migrate.php; las tablas nuevas van sólo ahí, no en schema.sql):

• learning_objects + learning_object_versions: la verdad del payload está en learning_object_versions.payload (JSON completo, incluida la cadena de sincronización por tipo de bloque); learning_objects guarda metadatos, slug y current_version_id. Cada publicación crea una versión nueva, nunca sobrescribe.
• assets + storage/lo/{id}/assets/: los materiales viven en disco; los bloques figure/image referencian rutas locales assets/… adjuntadas en base64 en el bundle.
• circles (jerarquía autorreferencial) y circle_objects/circle_shows: la relación círculo ↔ contenido.
• collections + collection_objects: rutas de aprendizaje enlazadas.
• content_taxonomy (migración 073): facetas normalizadas (nivel, materia, campo, dificultad, disciplina, plan) que alimentan el navegador /explora y las bandas de localización rápida.
• content_relations: la capa Weave — la red de conexiones que navega La Matrix (/matrix, alias técnico /brain) junto al Mapa del Conocimiento (/map) y los conceptos (/explorar, /conceptos/{slug}).
• shows + show_versions + show_attempts: el show guarda su historial versionado y el progreso por escena.
• autoeval_questions / autoeval_sessions: la autoevaluación registrada, con score, percent, valoración personal y needs_help.

Publicación y API

• El pipeline local es ObjectPublisher::ingest → LearningObject::publish: valida contra SchemaValidator, sanea (Sanitizer), verifica trazabilidad (EvidenceValidator) y versiona el documento completo.
• La API pública para agentes vive en /api/v1: GET /api/v1/objects/schema expone el contrato crudo, POST /api/v1/objects publica, y cada familia tiene su validador sin efectos (/api/v1/labs/validate, /games/validate, /tours/validate, /shows/validate, /apps/validate) que responde 422 con la lista de errores para reintentar. Ver el contrato completo en /agentes.
• Las tablas curriculares (curriculum_frameworks, curriculum_requirements, oa_curriculum_alignment, migración 076) guardan el fundamento oficial normalizado: el code del requisito es la identidad portable (única mundial), mientras su id es local a cada nodo — por eso el fundamento viaja por código y no por ids.
• El flujo de publicación pasa por Central (canal de distribución entre proyectos): Central autoría y publica; FRS consume lo escolar.

Glosario rápido

• OA — objeto de aprendizaje, la unidad de contenido escolar.
• lumbre-lo/1.0 — el formato JSON que describe un OA completo.
• Bloque — pieza atómica del contenido: una pregunta, un gráfico, una escena visual.
• Payload — el documento JSON versionado de un OA publicado.
• Asset — material binario (imagen, audio) servido por /media/lo/{id}/….
• Apoyo — OA de refuerzo con slug apo-… etiquetado por necesidad.
• Alignment — anclaje del bloque o del OA con un progreso de aprendizaje del plan SEP.
• Fundamento (curriculum) — raíz estructural del OA que lo ancla a requisitos oficiales trazables y viaja en la sincronización.
• CDIA — el currículo SEP (guías de orientación y alignment) que alinea el contenido.
• Weave — capa de relaciones entre contenidos (content_relations).