🎓 Miss J's Educational Program Generator

Inspirado en SCP-5094 — "Miss J's Whimsical Campfire"

Software educativo con estética retro CRT que genera programas de aprendizaje personalizados usando inteligencia artificial. La "profesora virtual" Miss J crea lecciones, evaluaciones y narración por voz sobre cualquier tema que el usuario elija.

✨ Características

Funcionalidad	Descripción
🖥️ Interfaz CRT Retro	Pantalla con efecto de monitor antiguo, scanlines, fosforescencia y pizarrón verde
🤖 Generación con IA	Contenido educativo generado por OpenAI GPT-4o-mini adaptado al tema y nivel
🔊 Text-to-Speech	Narración de lecciones con ElevenLabs o OpenAI TTS (fallback automático)
💾 Persistencia	Programas guardados en PostgreSQL para no consumir tokens al revisitar
📋 Temas Guardados	Sección para acceder a programas generados previamente
🎵 Cache de Audio	Audio TTS almacenado en DB para evitar regenerar
📝 Evaluaciones	Quiz automático al final de cada programa
🎭 Miss J Animada	Sprite animado con diferentes poses según el contexto

🏗️ Arquitectura

┌─────────────────┐     ┌──────────────────┐     ┌──────────────┐
│   Frontend      │     │   Backend        │     │  Services    │
│   (Vite)        │────▸│   (Express)      │────▸│              │
│                 │     │                  │     │  OpenAI API  │
│  - HTML/CSS/JS  │     │  /api/health     │     │  ElevenLabs  │
│  - CRT Effects  │     │  /api/generate   │     │  PostgreSQL  │
│  - Audio Player │     │  /api/tts        │     │              │
│  - UI Controller│     │  /api/programs   │     └──────────────┘
└─────────────────┘     └──────────────────┘
    :5173                   :3001

📁 Estructura del Proyecto

Proyecto-5094/
├── assets/                    # Assets del proyecto
│   └── main.png               # Sprite sheet de Miss J
├── server/                    # Backend (Express)
│   ├── index.js               # Servidor principal
│   ├── routes/
│   │   ├── content.js         # Generación de contenido (/api/generate-program)
│   │   ├── programs.js        # CRUD de programas guardados (/api/programs)
│   │   └── tts.js             # Text-to-Speech con cache (/api/tts)
│   └── services/
│       ├── ai-content.js      # Servicio de generación con OpenAI
│       ├── database.js        # Conexión y queries PostgreSQL
│       ├── prompt-builder.js  # Constructor de prompts educativos
│       └── tts-service.js     # TTS con ElevenLabs/OpenAI + fallback
├── src/
│   ├── css/
│   │   ├── main.css           # Estilos principales y design system
│   │   ├── crt-effect.css     # Efectos de monitor CRT
│   │   ├── chalkboard.css     # Estilos del pizarrón
│   │   └── animations.css     # Animaciones y transiciones
│   └── js/
│       ├── app.js             # Aplicación principal (orquestador)
│       ├── api-client.js      # Cliente API con fallback a demo
│       ├── ui-controller.js   # Controlador de eventos UI
│       ├── audio-player.js    # Reproductor de audio TTS
│       ├── character.js       # Controlador de sprites de Miss J
│       ├── lesson-renderer.js # Renderizador de lecciones
│       └── crt-effects.js     # Efectos visuales CRT
├── index.html                 # Página principal
├── vite.config.js             # Configuración de Vite + proxy API
├── package.json
├── .env.example               # Template de variables de entorno
└── .gitignore

🚀 Instalación y Ejecución

Requisitos Previos

Node.js v18+
PostgreSQL (servidor accesible, local o remoto)
API Key de OpenAI (para generación de contenido)
API Key de ElevenLabs (opcional, para TTS de mayor calidad)

1. Clonar el repositorio

git clone https://github.com/Vcarreon439/Proyecto-5094.git
cd Proyecto-5094

2. Instalar dependencias

npm install

3. Configurar variables de entorno

Copiar el archivo de ejemplo y completar con tus credenciales:

cp .env.example .env

Editar .env con tus valores:

# --- AI Content Generation ---
OPENAI_API_KEY=sk-proj-tu-api-key-aqui

# --- Text-to-Speech ---
ELEVENLABS_API_KEY=tu-elevenlabs-key-aqui     # Opcional
ELEVENLABS_VOICE_ID=tu-voice-id-aqui          # Opcional

# --- Server ---
PORT=3001
NODE_ENV=development
MAX_LESSONS=5                                  # Máximo de lecciones por programa

# --- Database (PostgreSQL) ---
DB_HOST=localhost
DB_PORT=5432
DB_NAME=miss_j_edu
DB_USER=postgres
DB_PASSWORD=tu-password

4. Crear la base de datos

Crear la base de datos en PostgreSQL (las tablas se crean automáticamente al iniciar el servidor):

CREATE DATABASE miss_j_edu;

5. Ejecutar el proyecto

Opción A — Dos terminales:

# Terminal 1: Backend
npm run server

# Terminal 2: Frontend
npm run dev

Opción B — Un solo comando (requiere concurrently):

npm install -D concurrently
npm run dev:full

6. Acceder a la aplicación

Abrir en el navegador: http://localhost:5173/

⚙️ Variables de Entorno

Variable	Requerida	Default	Descripción
`OPENAI_API_KEY`	✅ Sí	—	API key de OpenAI para generación de contenido
`ELEVENLABS_API_KEY`	❌ No	—	API key de ElevenLabs para TTS de alta calidad
`ELEVENLABS_VOICE_ID`	❌ No	`21m00Tcm4TlvDq8ikWAM`	ID de la voz de ElevenLabs (Rachel por defecto)
`PORT`	❌ No	`3001`	Puerto del servidor backend
`NODE_ENV`	❌ No	`development`	Entorno de ejecución
`MAX_LESSONS`	❌ No	`5`	Número máximo de lecciones permitidas por programa
`DB_HOST`	✅ Sí	`localhost`	Host del servidor PostgreSQL
`DB_PORT`	❌ No	`5432`	Puerto de PostgreSQL
`DB_NAME`	❌ No	`miss_j_edu`	Nombre de la base de datos
`DB_USER`	✅ Sí	`postgres`	Usuario de PostgreSQL
`DB_PASSWORD`	✅ Sí	`postgres`	Contraseña de PostgreSQL
`DATABASE_URL`	❌ No	—	URL de conexión completa (alternativa a variables individuales)

📡 API Endpoints

`GET /api/health`

Health check del servidor. Devuelve estado de servicios y configuración.

{
  "status": "ok",
  "version": "5.094",
  "maxLessons": 5,
  "services": {
    "ai": true,
    "tts": true,
    "database": true
  }
}

`POST /api/generate-program`

Genera un programa educativo completo con IA.

Body:

{
  "topic": "Volcanes",
  "difficulty": "basico",
  "lessonCount": 5
}

`GET /api/programs`

Lista todos los programas guardados.

`GET /api/programs/:id`

Obtiene un programa completo por ID (con todas las lecciones y quiz).

`DELETE /api/programs/:id`

Elimina un programa guardado y su audio cacheado.

`POST /api/tts`

Genera audio TTS con cache automático.

Body:

{
  "text": "Texto a convertir en voz",
  "programId": 1,
  "lessonIndex": 0
}

🗄️ Base de Datos

El servidor crea automáticamente las tablas necesarias al iniciar:

Tabla `programs`

Almacena los programas educativos generados.

Columna	Tipo	Descripción
`id`	`SERIAL`	Identificador único
`topic`	`VARCHAR(500)`	Tema del programa
`difficulty`	`VARCHAR(50)`	Nivel de dificultad
`title`	`VARCHAR(500)`	Título generado por IA
`description`	`TEXT`	Descripción del programa
`lesson_count`	`INTEGER`	Número de lecciones
`program_data`	`JSONB`	Datos completos (lecciones, quiz)
`created_at`	`TIMESTAMPTZ`	Fecha de creación

Tabla `audio_cache`

Cache de audio TTS para evitar regenerar.

Columna	Tipo	Descripción
`id`	`SERIAL`	Identificador único
`program_id`	`INTEGER`	FK a programs
`lesson_index`	`INTEGER`	Índice de la lección
`audio_text_hash`	`VARCHAR(64)`	Hash del texto (para reusar)
`audio_data`	`BYTEA`	Audio MP3 binario

🔊 Text-to-Speech

El sistema de TTS tiene un mecanismo de fallback automático:

ElevenLabs (si está configurada) → Voz multilingüe de alta calidad
OpenAI TTS (fallback) → Voz "nova" (femenina, cálida)
Sin audio → La aplicación funciona sin TTS

Voces premade de ElevenLabs (compatibles con plan gratuito):

Voice ID	Nombre	Estilo
`21m00Tcm4TlvDq8ikWAM`	Rachel	Calmada, narración
`AZnzlk1XvdvUeBnXmlld`	Domi	Fuerte, clara
`EXAVITQu4vr4xnSDxMaL`	Sarah	Suave, cálida
`MF3mGyEYCl7XYWbV9V6O`	Emily	Calmada, gentil

🎨 Stack Tecnológico

Capa	Tecnología
Frontend	HTML5, CSS3 (Vanilla), JavaScript ES Modules
Bundler	Vite 7
Backend	Node.js, Express 5
IA	OpenAI GPT-4o-mini
TTS	ElevenLabs / OpenAI TTS
Base de datos	PostgreSQL
Tipografías	VT323, Press Start 2P, Patrick Hand (Google Fonts)

📜 Licencia

Este proyecto es software educativo y de investigación, inspirado en la obra ficticia SCP-5094 de la SCP Foundation Wiki bajo licencia Creative Commons SA 3.0.

Desarrollado con 📚 por JadeEdTech — v5.094

Navigation Menu

Repository files navigation

🎓 Miss J's Educational Program Generator

✨ Características

🏗️ Arquitectura

📁 Estructura del Proyecto

🚀 Instalación y Ejecución

Requisitos Previos

1. Clonar el repositorio

2. Instalar dependencias

3. Configurar variables de entorno

4. Crear la base de datos

5. Ejecutar el proyecto

6. Acceder a la aplicación

⚙️ Variables de Entorno

📡 API Endpoints

`GET /api/health`

`POST /api/generate-program`

`GET /api/programs`

`GET /api/programs/:id`

`DELETE /api/programs/:id`

`POST /api/tts`

🗄️ Base de Datos

Tabla `programs`

Tabla `audio_cache`

🔊 Text-to-Speech

Voces premade de ElevenLabs (compatibles con plan gratuito):

🎨 Stack Tecnológico

📜 Licencia

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
assets		assets
public		public
server		server
src		src
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
vite.config.js		vite.config.js

Latest commit

History

Folders and files

Repository files navigation

🎓 Miss J's Educational Program Generator

✨ Características

🏗️ Arquitectura

📁 Estructura del Proyecto

🚀 Instalación y Ejecución

Requisitos Previos

1. Clonar el repositorio

2. Instalar dependencias

3. Configurar variables de entorno

4. Crear la base de datos

5. Ejecutar el proyecto

6. Acceder a la aplicación

⚙️ Variables de Entorno

📡 API Endpoints

GET /api/health

POST /api/generate-program

GET /api/programs

GET /api/programs/:id

DELETE /api/programs/:id

POST /api/tts

🗄️ Base de Datos

Tabla programs

Tabla audio_cache

🔊 Text-to-Speech

Voces premade de ElevenLabs (compatibles con plan gratuito):

🎨 Stack Tecnológico

📜 Licencia

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`GET /api/health`

`POST /api/generate-program`

`GET /api/programs`

`GET /api/programs/:id`

`DELETE /api/programs/:id`

`POST /api/tts`

Tabla `programs`

Tabla `audio_cache`