LearnSpark AI — Intelligent Tutoring Platform

Concepto

LearnSpark AI es un MVP de tutoría inteligente que personaliza el aprendizaje para estudiantes de secundaria y bachillerato. Combina evaluación adaptativa, rutas de aprendizaje generadas por IA, un tutor conversacional 24/7 con RAG, y generación dinámica de ejercicios — todo en una API RESTful segura con JWT.

---

Arquitectura

┌─────────────────────────────────────────────────────────────┐
│                      CLIENT (Web / App)                     │
└────────────────────────┬────────────────────────────────────┘
                         │ HTTPS + Bearer JWT
┌────────────────────────▼────────────────────────────────────┐
│               Spring Boot 4 / Java 25 API                   │
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
│  │AuthController│  │AssessmentCtl│  │  ChatController     │ │
│  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘ │
│         │                │                     │            │
│  ┌──────▼──────────────────────────────────────▼──────────┐ │
│  │   UserService  AssessmentService  ChatService  ...     │ │
│  └──────────────────────────┬───────────────────────────  ┘ │
│                             │                               │
│  ┌──────────────────────────▼─────────────────────────────┐ │
│  │  VectorDBService (in-memory RAG)  │  AIService (LLM)   │ │
│  └──────────────────────────┬────────────────────┬────────┘ │
│                             │                    │          │
│  ┌──────────────────────────▼────────┐    ┌──────▼────────┐ │
│  │  H2 / PostgreSQL (Spring Data JPA)│    │  LLMClient    │ │
│  │  Users, Progress, LearningPaths,  │    │  (Feign →     │ │
│  │  Exercises, Subjects              │    │   GPT-4o API) │ │
│  └───────────────────────────────────┘    └───────────────┘ │
└─────────────────────────────────────────────────────────────┘

Capas

Capa	Paquete	Responsabilidad
Controller	controller/	REST endpoints, validación Jakarta, manejo global de errores
Service	service/	Lógica de negocio, orquestación de IA
Repository	repository/	Spring Data JPA, acceso a datos
Model	model/	Entidades JPA (User, Subject, LearningPath, Progress, Exercise)
DTO	dto/	Records Java 25 inmutables para requests/responses
Security	security/	JWT (jjwt 0.12.x), UserDetails, filtro stateless
Client	client/	Feign client OpenAI-compatible

---

Endpoints

Auth — público

Método	Path	Descripción
POST	/api/v1/auth/register	Registro de nuevo estudiante → JWT
POST	/api/v1/auth/login	Login con email+password → JWT

Ejemplo register:

POST /api/v1/auth/register
{
  "name": "María García",
  "email": "maria@example.com",
  "password": "securePass1",
  "gradeLevel": "10th Grade"
}

Assessment — Feature 1: Evaluación de Nivel

Método	Path	Descripción
GET	/api/v1/assessment/questions?subjectId=1	Obtener preguntas adaptativas
POST	/api/v1/assessment	Enviar respuestas → score + ruta de aprendizaje

Ejemplo submit:

POST /api/v1/assessment
Authorization: Bearer <token>
{
  "subjectId": 1,
  "answers": [
    {"questionId": "le-1", "answer": "x=4"},
    {"questionId": "q-1", "answer": "(x+2)(x+3)"}
  ]
}

Learning Path — Feature 2: Ruta Personalizada

Método	Path	Descripción
GET	/api/v1/me/learning-path	Rutas del estudiante autenticado
GET	/api/v1/me/learning-path/{id}	Ruta por ID con lecciones ordenadas

Chat — Feature 3: Tutor Conversacional 24/7

Método	Path	Descripción
POST	/api/v1/chat	Mensaje al tutor → respuesta con RAG + fuentes

Ejemplo:

POST /api/v1/chat
Authorization: Bearer <token>
{
  "message": "How do I solve a quadratic equation?",
  "subjectId": 1
}

Practice — Feature 4: Generador de Práctica Dinámica

Método	Path	Descripción
POST	/api/v1/practice/generate	Genera ejercicios por área débil

Ejemplo:

POST /api/v1/practice/generate
Authorization: Bearer <token>
{
  "subjectId": 1,
  "topic": "quadratic",
  "difficulty": "MEDIUM",
  "count": 5
}

Progress — Feature 5: Dashboard de Progreso

Método	Path	Descripción
GET	/api/v1/me/progress	Score, minutos de estudio, áreas débiles por materia

---

RAG Implementation

VectorDBService mantiene un corpus en memoria de snippets curriculares (8 snippets de Álgebra pre-cargados). Usa overlap de tokens (keyword matching) como proxy de similitud vectorial — suficiente para el MVP.

Flujo en /api/v1/chat:

1. VectorDBService.search(message, 3) → top-3 snippets relevantes
2. Los snippets se inyectan en el system prompt del LLM
3. AIService llama al Feign client; si falla (sin API key real), devuelve respuesta mock curricular

En producción: reemplazar VectorDBService con cliente a pgvector/Pinecone/Weaviate.

---

Análisis de Negocio

Problema

Aprendizaje online genérico → frustración, deserción, bajo rendimiento académico.

Solución

Personalización real a escala mediante IA: evaluación → ruta → práctica → tutor.

Modelo de Monetización (SaaS)

Plan	Precio	Incluye
Básico	$9.99/mes	1 materia, tutor 24/7, 50 ejercicios/día
Premium	$19.99/mes	Todas las materias, ejercicios ilimitados
Familiar	$29.99/mes	Premium + dashboard para padres, 3 estudiantes
Institución	Custom	API white-label, analíticas avanzadas

Métricas Clave (KPIs)

• MAU (Monthly Active Users)
• Tasa de retención 30/60/90 días
• Mejora de score pre→post assessment
• NPS (Net Promoter Score) padres/estudiantes

Ventaja Competitiva

• Data flywheel: cada sesión mejora el modelo adaptativo
• Personalización real por estudiante (no por cohorte)
• Integrable con cualquier LLM (Feign abstraction)

---

Cómo Ejecutar

Requisitos

• Java 25+
• Maven 3.9+

Dev (H2 en memoria)

cd solutions/2026-05-10-learnspark-ai-tutor

# Opción 1: activar perfil dev explícitamente
mvn spring-boot:run -Dspring-boot.run.profiles=dev

# Opción 2: sin perfil (usa defaults en AppProperties)
mvn spring-boot:run

La base de datos H2 se crea automáticamente. El DataInitializer siembra:

• 4 materias: Algebra, Calculus, Geometry, Physics
• 8 ejercicios de Algebra de ejemplo

Consola H2 (solo con perfil dev)

http://localhost:8080/h2-console

• JDBC URL: jdbc:h2:mem:learnspark
• User: sa / Password: (vacío)

Con LLM real (GPT-4o)

# application-prod.yml o variable de entorno
app:
  jwt:
    secret: "your-256-bit-secret-here"
  llm:
    api-key: "sk-..."
    base-url: "https://api.openai.com"
    model: "gpt-4o"

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/learnspark
    username: postgres
    password: yourpassword

mvn spring-boot:run -Dspring-boot.run.profiles=prod

Flujo de prueba rápida

# 1. Registrar
curl -s -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name":"Ana","email":"ana@test.com","password":"password1","gradeLevel":"10th"}' | jq .

# 2. Login → guardar token
TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"ana@test.com","password":"password1"}' | jq -r '.data.token')

# 3. Obtener preguntas
curl -s http://localhost:8080/api/v1/assessment/questions?subjectId=1 \
  -H "Authorization: Bearer $TOKEN" | jq .

# 4. Enviar respuestas y obtener ruta
curl -s -X POST http://localhost:8080/api/v1/assessment \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"subjectId":1,"answers":[{"questionId":"le-1","answer":"x=4"},{"questionId":"q-1","answer":"(x+2)(x+3)"}]}' | jq .

# 5. Chatear con el tutor
curl -s -X POST http://localhost:8080/api/v1/chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"How do I solve quadratic equations?","subjectId":1}' | jq .

# 6. Generar práctica
curl -s -X POST http://localhost:8080/api/v1/practice/generate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"subjectId":1,"topic":"quadratic","difficulty":"MEDIUM","count":3}' | jq .

# 7. Ver progreso
curl -s http://localhost:8080/api/v1/me/progress \
  -H "Authorization: Bearer $TOKEN" | jq .

---

Referencias

• Innovative AI App Ideas 2025
• Spring Boot 4 Reference
• Spring Security 7 Reference
• jjwt 0.12.x Docs
• Spring Cloud OpenFeign