Complete Guide · Guía Completa
Everything you need to know about the Interactive Typographic Light-Tree
Todo lo que necesitas saber sobre el Árbol Tipográfico de Luz Interactivo
Table of Contents · Tabla de Contenidos
1. Project Objective
English
The Interactive Typographic Light-Tree creates a minimalist, interactive Christmas decoration that combines physical art with digital experiences. A triangle of LED lights on your wall becomes a canvas for printed bilingual words (Spanish and English) that form a typographic tree.
At the top of the tree sits a star with one QR code. When scanned, this code connects to our web platform, which randomly selects a keyword from your group's custom database and uses AI (ChatGPT) to generate a unique bilingual activity, story, or reflection.
Goal: Create meaningful, spontaneous moments during Christmas gatherings by combining minimalist design, technology, and personalized content that brings people together.
Español
El Árbol Tipográfico de Luz Interactivo crea una decoración navideña minimalista e interactiva que combina arte físico con experiencias digitales. Un triángulo de luces LED en tu pared se convierte en un lienzo para palabras bilingües impresas (español e inglés) que forman un árbol tipográfico.
En la parte superior del árbol hay una estrella con un código QR. Al escanearlo, este código se conecta a nuestra plataforma web, que selecciona aleatoriamente una palabra clave de la base de datos personalizada de tu grupo y usa IA (ChatGPT) para generar una actividad, historia o reflexión bilingüe única.
Objetivo: Crear momentos significativos y espontáneos durante las reuniones navideñas combinando diseño minimalista, tecnología y contenido personalizado que une a las personas.
2. Understanding Groups
English
What is a Group? A group is an isolated workspace where you and your family/friends can create and share personalized Christmas experiences. Each group has:
- ✓Unique Group Code: A permanent identifier (e.g., "xmas-family-2025-abc123")
- ✓Display Name: A friendly name like "Garcia Family Christmas 2025"
- ✓Passphrase Protection: A secure password (12+ characters) to control access
- ✓Custom Keywords Database: 100-1000 bilingual keyword entries unique to your group
- ✓Activity Tracking: Logs of who accessed the group and when experiences were generated
Complete Isolation: Groups never share data. Your keywords, experiences, and activity logs are completely private to your group.
Español
¿Qué es un Grupo? Un grupo es un espacio de trabajo aislado donde tú y tu familia/amigos pueden crear y compartir experiencias navideñas personalizadas. Cada grupo tiene:
- ✓Código de Grupo Único: Un identificador permanente (ej. "xmas-familia-2025-abc123")
- ✓Nombre de Visualización: Un nombre amigable como "Navidad Familia García 2025"
- ✓Protección con Contraseña: Una contraseña segura (12+ caracteres) para controlar el acceso
- ✓Base de Datos de Palabras Clave Personalizadas: 100-1000 entradas bilingües únicas para tu grupo
- ✓Seguimiento de Actividad: Registros de quién accedió al grupo y cuándo se generaron experiencias
Aislamiento Completo: Los grupos nunca comparten datos. Tus palabras clave, experiencias y registros de actividad son completamente privados para tu grupo.
3. Adding Group Members
English
There are two ways to add new members to your group:
Method 1: Share Group Code + Passphrase
- Give the new member your group code (e.g., "xmas-family-2025-abc123")
- Share the group passphrase (via secure channel - text, email, in person)
- They visit the homepage and enter the group code
- They'll be prompted to enter the passphrase to access the group
- Once authenticated, they have full access to generate experiences
Method 2: Scan Group QR Code (Recommended)
- After logging into your group, scroll to the "Share with Others" section
- Show the QR code to the new member (or send them a screenshot)
- They scan the QR code with their phone camera
- They'll be taken directly to the group authentication page
- They enter the group passphrase to gain access
- They're now part of the group and can generate experiences
⭐ This method is faster and prevents typos in the group code!
🔐 Security Note:
The passphrase is required for first-time access. Once someone authenticates successfully, their device receives a 7-day session cookie. They won't need to re-enter the passphrase for 7 days.
Español
Hay dos formas de agregar nuevos miembros a tu grupo:
Método 1: Compartir Código + Contraseña
- Dale al nuevo miembro tu código de grupo (ej. "xmas-familia-2025-abc123")
- Comparte la contraseña del grupo (por canal seguro - texto, email, en persona)
- Visitan la página de inicio e ingresan el código de grupo
- Se les pedirá ingresar la contraseña para acceder al grupo
- Una vez autenticados, tienen acceso completo para generar experiencias
Método 2: Escanear Código QR del Grupo (Recomendado)
- Después de iniciar sesión en tu grupo, desplázate a "Compartir con Otros"
- Muestra el código QR al nuevo miembro (o envíales una captura de pantalla)
- Escanean el código QR con la cámara de su teléfono
- Serán llevados directamente a la página de autenticación del grupo
- Ingresan la contraseña del grupo para obtener acceso
- Ahora son parte del grupo y pueden generar experiencias
⭐ ¡Este método es más rápido y previene errores de escritura en el código!
🔐 Nota de Seguridad:
La contraseña es requerida para el acceso inicial. Una vez que alguien se autentica exitosamente, su dispositivo recibe una cookie de sesión de 7 días. No necesitarán volver a ingresar la contraseña por 7 días.
5. Keywords System
English
Keywords are the foundation of your group's experiences. Each keyword consists of a bilingual label (Spanish + English) and bilingual prompts that guide the AI in creating personalized content.
📋 Keyword Structure
Each keyword entry contains:
- •ID: Unique number (1-1000)
- •label_es: Spanish label (2-3 words, e.g., "Gratitud")
- •label_en: English label (2-3 words, e.g., "Gratitude")
- •prompt_es: Spanish content prompt (200-400 words describing the activity/story)
- •prompt_en: English content prompt (200-400 words describing the activity/story)
📊 Database Requirements
- ✓Minimum: 100 keyword entries
- ✓Maximum: 1000 keyword entries
- ✓Format: CSV file with headers (id, label_es, label_en, prompt_es, prompt_en)
- ✓Encoding: UTF-8 (to support Spanish characters like ñ, á, etc.)
🎯 Two Ways to Create Keywords
Option 1: Upload CSV File
If you already have a CSV file with bilingual keywords, you can upload it directly. The system validates the format and ensures all required columns are present.
Option 2: AI-Powered Generation (Recommended)
Use our intelligent 3-step wizard to generate custom keywords with AI. You define quantity, topics, and guidelines—the AI creates everything. See section 6 for details.
💡 Default Keywords
New groups start with a default set of 120 family-friendly bilingual keywords covering topics like gratitude, family stories, Christmas traditions, and simple games. You can replace these at any time by uploading a custom CSV or using the AI wizard.
Español
Las palabras clave son la base de las experiencias de tu grupo. Cada palabra clave consiste en una etiqueta bilingüe (español + inglés) y prompts bilingües que guían a la IA en la creación de contenido personalizado.
📋 Estructura de Palabra Clave
Cada entrada contiene:
- •ID: Número único (1-1000)
- •label_es: Etiqueta en español (2-3 palabras, ej. "Gratitud")
- •label_en: Etiqueta en inglés (2-3 palabras, ej. "Gratitude")
- •prompt_es: Prompt de contenido en español (200-400 palabras describiendo la actividad)
- •prompt_en: Prompt de contenido en inglés (200-400 palabras describiendo la actividad)
📊 Requisitos de la Base de Datos
- ✓Mínimo: 100 palabras clave
- ✓Máximo: 1000 palabras clave
- ✓Formato: Archivo CSV con encabezados (id, label_es, label_en, prompt_es, prompt_en)
- ✓Codificación: UTF-8 (para soportar caracteres españoles como ñ, á, etc.)
🎯 Dos Formas de Crear Palabras Clave
Opción 1: Subir Archivo CSV
Si ya tienes un archivo CSV con palabras clave bilingües, puedes subirlo directamente. El sistema valida el formato y asegura que todas las columnas requeridas estén presentes.
Opción 2: Generación con IA (Recomendado)
Usa nuestro asistente inteligente de 3 pasos para generar palabras clave personalizadas con IA. Defines cantidad, temas y guías—la IA crea todo. Ver sección 6 para detalles.
💡 Palabras Clave Predeterminadas
Los nuevos grupos comienzan con un conjunto predeterminado de 120 palabras clave bilingües familiares que cubren temas como gratitud, historias familiares, tradiciones navideñas y juegos simples. Puedes reemplazarlas en cualquier momento subiendo un CSV personalizado o usando el asistente de IA.
6. AI Keyword Generator Wizard (Detailed)
English
The AI Keyword Generator is a powerful 3-step wizard that creates custom bilingual keywords automatically using ChatGPT (gpt-4o-mini model). No manual writing required!
Step 1: Keyword Quantity
Choose how many keyword entries you want to generate:
- →Minimum: 100 keywords
- →Maximum: 1000 keywords
- →Recommendation: 200-500 keywords provides good variety without overwhelming
💡 Tip: More keywords = more variety in experiences. The app randomly selects one each time someone scans the QR code.
Step 2: Topic Labels
Define 3-10 topic labels that categorize your keywords. The AI distributes keywords evenly across these topics.
Examples of Topic Labels:
- • Gratitude (Gratitud)
- • Family Stories (Historias Familiares)
- • Christmas Traditions (Tradiciones Navideñas)
- • Fun Games (Juegos Divertidos)
- • Acts of Kindness (Actos de Bondad)
- • Favorite Memories (Recuerdos Favoritos)
- • Holiday Recipes (Recetas Navideñas)
⭐ How it works: If you choose 300 keywords and 6 labels, the AI generates ~50 keywords per label, ensuring balanced variety.
Step 3: Content Guidelines
Customize how the AI generates content with detailed options:
🎯 Target Audience
- • All Ages (8+): Family-friendly, simple vocabulary
- • Teens & Adults (13+): Moderate complexity
- • Adults Only (18+): Advanced vocabulary, deeper topics
📏 Activity Length
- • Short (1-2 min): 100-150 words per language
- • Medium (2-5 min): 200-400 words per language (recommended)
- • Long (5-10 min): 400-600 words per language
🎨 Content Style
- • Tones: Warm, Playful, Reflective, Humorous, Heartfelt
- • Activity Types: Storytelling, Games, Questions, Crafts, Reflections
- • Complexity: Simple, Moderate, or Advanced vocabulary
🛡️ Safety Guardrails
Default Guardrails (Recommended): The system automatically excludes sensitive topics:
- ✗ Religion
- ✗ Politics
- ✗ Violence
- ✗ Intimate matters
- ✗ Money/Wealth
- ✗ Health/Medical
- ✗ Death/Loss
- ✗ Controversial topics
💚 You can disable these if you want full creative freedom, or add your own custom avoid-topics.
🌍 Language & Culture
- • Primary Language: Spanish or English (AI writes better in primary)
- • Cultural Focus: Mexican, Spanish, Latin American, US/International
- • Both languages always generated—this just affects cultural nuances
Generation Process
After you click "Generate", the wizard:
- Creates a generation job and shows progress in real-time
- Generates keywords in batches of 50 (to avoid API limits)
- Validates each batch against your guardrails
- Regenerates any filtered entries to reach exact count
- Formats everything into a proper CSV file
- Shows a preview of the first 10 entries
- Allows you to download OR save directly to your group
⏱️ Time: Generation takes 1-3 minutes for 100 keywords, up to 10-15 minutes for 1000 keywords. The page updates in real-time with progress!
After Generation
Once generation completes, you have two options:
📥 Download CSV
Download the CSV file to your computer. Opens in Excel/Google Sheets. You can review, edit, and upload later.
✓ Save & Use
Immediately replace your group's current keywords with the generated ones. The new keywords become active instantly for all group members.
⚠️ Note: "Save & Use" creates a backup of your old keywords automatically. You can find backups in your group data folder with timestamps.
Español
El Generador de Palabras Clave con IA es un poderoso asistente de 3 pasos que crea palabras clave bilingües personalizadas automáticamente usando ChatGPT (modelo gpt-4o-mini). ¡No requiere escritura manual!
Paso 1: Cantidad de Palabras Clave
Elige cuántas entradas quieres generar:
- →Mínimo: 100 palabras clave
- →Máximo: 1000 palabras clave
- →Recomendación: 200-500 palabras clave proporciona buena variedad sin abrumar
💡 Consejo: Más palabras clave = más variedad en experiencias. La app selecciona una al azar cada vez que alguien escanea el QR.
Paso 2: Etiquetas de Tema
Define 3-10 etiquetas de tema que categorizan tus palabras clave. La IA distribuye las palabras uniformemente entre estos temas.
Ejemplos de Etiquetas de Tema:
- • Gratitud (Gratitude)
- • Historias Familiares (Family Stories)
- • Tradiciones Navideñas (Christmas Traditions)
- • Juegos Divertidos (Fun Games)
- • Actos de Bondad (Acts of Kindness)
- • Recuerdos Favoritos (Favorite Memories)
- • Recetas Navideñas (Holiday Recipes)
⭐ Cómo funciona: Si eliges 300 palabras clave y 6 etiquetas, la IA genera ~50 palabras por etiqueta, asegurando variedad balanceada.
Paso 3: Guías de Contenido
Personaliza cómo la IA genera contenido con opciones detalladas:
🎯 Audiencia Objetivo
- • Todas las Edades (8+): Familiar, vocabulario simple
- • Adolescentes y Adultos (13+): Complejidad moderada
- • Solo Adultos (18+): Vocabulario avanzado, temas profundos
📏 Duración de Actividad
- • Corta (1-2 min): 100-150 palabras por idioma
- • Media (2-5 min): 200-400 palabras por idioma (recomendado)
- • Larga (5-10 min): 400-600 palabras por idioma
🎨 Estilo de Contenido
- • Tonos: Cálido, Juguetón, Reflexivo, Humorístico, Sincero
- • Tipos de Actividad: Narración, Juegos, Preguntas, Manualidades, Reflexiones
- • Complejidad: Vocabulario Simple, Moderado o Avanzado
🛡️ Protecciones de Seguridad
Protecciones Predeterminadas (Recomendado): El sistema excluye automáticamente temas sensibles:
- ✗ Religión
- ✗ Política
- ✗ Violencia
- ✗ Asuntos íntimos
- ✗ Dinero/Riqueza
- ✗ Salud/Médico
- ✗ Muerte/Pérdida
- ✗ Temas controversiales
💚 Puedes desactivar estos si quieres libertad creativa completa, o agregar tus propios temas a evitar.
🌍 Idioma y Cultura
- • Idioma Principal: Español o Inglés (IA escribe mejor en primario)
- • Enfoque Cultural: Mexicano, Español, Latinoamericano, EE.UU./Internacional
- • Ambos idiomas siempre se generan—esto solo afecta matices culturales
Proceso de Generación
Después de hacer clic en "Generar", el asistente:
- Crea un trabajo de generación y muestra progreso en tiempo real
- Genera palabras clave en lotes de 50 (para evitar límites de API)
- Valida cada lote contra tus protecciones
- Regenera cualquier entrada filtrada para alcanzar el conteo exacto
- Formatea todo en un archivo CSV apropiado
- Muestra una vista previa de las primeras 10 entradas
- Te permite descargar O guardar directamente a tu grupo
⏱️ Tiempo: La generación toma 1-3 minutos para 100 palabras clave, hasta 10-15 minutos para 1000. ¡La página se actualiza en tiempo real con el progreso!
Después de Generación
Una vez que la generación se completa, tienes dos opciones:
📥 Descargar CSV
Descarga el archivo CSV a tu computadora. Se abre en Excel/Google Sheets. Puedes revisar, editar y subir después.
✓ Guardar y Usar
Reemplaza inmediatamente las palabras clave actuales de tu grupo con las generadas. Las nuevas palabras clave se activan instantáneamente para todos los miembros.
⚠️ Nota: "Guardar y Usar" crea un respaldo de tus palabras clave antiguas automáticamente. Puedes encontrar respaldos en la carpeta de datos de tu grupo con marcas de tiempo.
7. Generating Experiences
English
Experiences are bilingual AI-generated activities, stories, or reflections created when someone scans the QR code or clicks "Generate Random Experience" in the group page.
🎯 How It Works
- User scans QR code on physical star OR clicks "Generate" button
- App randomly selects one keyword from your group's database (100-1000 possibilities)
- Selected keyword's prompt is sent to ChatGPT API (gpt-4o-mini)
- AI generates unique bilingual content based on the prompt
- Text-to-speech creates audio in both Spanish (Nova voice) and English (Alloy voice)
- User sees bilingual text + plays audio for immersive experience
🎲 Randomization
Every scan is different! The app uses true randomization:
- •Each scan picks a random keyword ID (e.g., keyword #47, then #123, then #8)
- •Even the same keyword generates different content each time (AI creativity)
- •With 100 keywords, you have 100+ unique experiences
- •With 1000 keywords, you have virtually unlimited variety
🔊 Audio Features
Each experience includes high-quality text-to-speech audio:
- ✓Spanish Audio: Nova voice (natural, expressive)
- ✓English Audio: Alloy voice (clear, friendly)
- ✓Integrated audio players in each language card
- ✓Perfect for accessibility and group listening
💡 Usage Tips
- →During Gatherings: Take turns scanning the QR code and reading/listening together
- →Daily Practice: Scan once per day for a Christmas reflection or activity
- →Language Learning: Read in one language, listen in the other
- →Keep Scanning: Don't like the first one? Scan again for something different!
Español
Las experiencias son actividades, historias o reflexiones bilingües generadas por IA cuando alguien escanea el código QR o hace clic en "Generar Experiencia Aleatoria" en la página del grupo.
🎯 Cómo Funciona
- El usuario escanea el código QR en la estrella física O hace clic en "Generar"
- La app selecciona aleatoriamente una palabra clave de la base de datos (100-1000 posibilidades)
- El prompt de la palabra clave seleccionada se envía a la API de ChatGPT (gpt-4o-mini)
- La IA genera contenido bilingüe único basado en el prompt
- Texto a voz crea audio en español (voz Nova) e inglés (voz Alloy)
- El usuario ve texto bilingüe + reproduce audio para experiencia inmersiva
🎲 Aleatorización
¡Cada escaneo es diferente! La app usa aleatorización verdadera:
- •Cada escaneo elige un ID de palabra clave al azar (ej. palabra #47, luego #123, luego #8)
- •Incluso la misma palabra clave genera contenido diferente cada vez (creatividad de IA)
- •Con 100 palabras clave, tienes 100+ experiencias únicas
- •Con 1000 palabras clave, tienes variedad virtualmente ilimitada
🔊 Características de Audio
Cada experiencia incluye audio de texto a voz de alta calidad:
- ✓Audio en Español: Voz Nova (natural, expresiva)
- ✓Audio en Inglés: Voz Alloy (clara, amigable)
- ✓Reproductores de audio integrados en cada tarjeta de idioma
- ✓Perfecto para accesibilidad y escucha grupal
💡 Consejos de Uso
- →Durante Reuniones: Túrnense para escanear el QR y leer/escuchar juntos
- →Práctica Diaria: Escanea una vez al día para una reflexión o actividad navideña
- →Aprendizaje de Idiomas: Lee en un idioma, escucha en el otro
- →Sigue Escaneando: ¿No te gusta el primero? ¡Escanea de nuevo para algo diferente!
8. Administrator Features
English
Administrators have access to a powerful dashboard for managing multiple groups, viewing analytics, and controlling group access.
🎛️ Admin Dashboard
Access at /admin with admin passphrase:
- •Dashboard Stats: Total groups, active groups, total experiences, active today
- •Group List: View all groups with display name, creation date, access count
- •Sorting: Sort by name, creation date, last accessed, or experience count
- •Filtering: Show all, active only, or inactive groups
➕ Creating Groups
From dashboard, click "Create New Group" to:
- Enter a display name (e.g., "Garcia Family Christmas 2025")
- Set a secure group passphrase (12+ characters required)
- System generates unique group code automatically
- Group initialized with default 120 keywords
- Group immediately accessible to members with passphrase
📊 Group Details
Click any group to view detailed information:
- ✓Metadata: Display name, group code, creation date, last modified
- ✓Keywords: Current keyword count, CSV upload history
- ✓Activity Log: Full history of accesses and experience generations
- ✓Device Info: IP addresses, user agents, device types (desktop/mobile/tablet)
🔧 Admin Actions
- →Edit Keywords: Admin can access group upload page (requires group passphrase)
- →Delete Group: Permanently remove group and all data (requires confirmation)
- →View Access: Bypass group passphrase to view group pages as admin
⚠️ Security Notes
- !Admin Passphrase: Set via environment variable, never stored in database
- !Group Passphrases: Hashed with bcrypt, cannot be recovered (only reset)
- !Rate Limiting: Failed login attempts tracked to prevent brute force
Español
Los administradores tienen acceso a un panel poderoso para gestionar múltiples grupos, ver analíticas y controlar el acceso a grupos.
🎛️ Panel de Administración
Accede en /admin con contraseña de administrador:
- •Estadísticas del Panel: Total de grupos, grupos activos, experiencias totales, activos hoy
- •Lista de Grupos: Ver todos los grupos con nombre, fecha de creación, conteo de accesos
- •Ordenamiento: Ordenar por nombre, fecha de creación, último acceso o conteo de experiencias
- •Filtrado: Mostrar todos, solo activos o grupos inactivos
➕ Crear Grupos
Desde el panel, haz clic en "Crear Nuevo Grupo" para:
- Ingresar un nombre de visualización (ej. "Navidad Familia García 2025")
- Establecer contraseña segura del grupo (12+ caracteres requeridos)
- El sistema genera código de grupo único automáticamente
- Grupo inicializado con 120 palabras clave predeterminadas
- Grupo inmediatamente accesible para miembros con contraseña
📊 Detalles del Grupo
Haz clic en cualquier grupo para ver información detallada:
- ✓Metadatos: Nombre, código de grupo, fecha de creación, última modificación
- ✓Palabras Clave: Conteo actual, historial de subidas CSV
- ✓Registro de Actividad: Historial completo de accesos y generaciones de experiencias
- ✓Info de Dispositivos: Direcciones IP, agentes de usuario, tipos de dispositivos
🔧 Acciones de Administrador
- →Editar Palabras Clave: Admin puede acceder a página de subida (requiere contraseña del grupo)
- →Eliminar Grupo: Remover permanentemente grupo y todos los datos (requiere confirmación)
- →Ver Acceso: Omitir contraseña del grupo para ver páginas como administrador
⚠️ Notas de Seguridad
- !Contraseña de Admin: Establecida por variable de entorno, nunca almacenada en base de datos
- !Contraseñas de Grupos: Hash con bcrypt, no se pueden recuperar (solo restablecer)
- !Limitación de Tasa: Intentos fallidos rastreados para prevenir fuerza bruta