LearnYos

Plataforma de aprendizaje con IA (Next.js)

Frontend de la plataforma de aprendizaje activo LearnYos construido con Next.js 14, React 18 y Tailwind CSS 3. Genera exámenes tipo quiz e ICFES, flashcards y notas con IA, con el tutor Junior IA y chat educativo en streaming. Consume la API REST del backend Klerk. Forma parte del sistema Kire junto a Klerk.

2026 · En producción

Demo en vivo ↗ Código ↗ Código backend ↗

LearnYos — captura del proyecto.

Contexto y propósito

LearnYos es el frontend del sistema educativo Kire (frontend learnyos-x2 + backend Klerk). El problema que ataca: estudiar para exámenes tipo ICFES / quiz es lento si el material hay que crearlo a mano. LearnYos lo genera con IA a partir de un tema o de archivos (PDF, imágenes) y lo convierte en exámenes jugables, flashcards y notas con Markdown + KaTeX.

Usuarios: estudiantes que practican, crean mazos y repasan; docentes o creadores que comparten material con códigos de 5 caracteres. El frontend debe renderizar contenido rico (Markdown, resaltado de código, fórmulas), manejar estados de generación asíncrona y no exponer nunca las keys de IA: todo pasa por Klerk.

Propósito declarado: Ayudar a estudiantes a preparar exámenes mediante generación con IA de preguntas, flashcards, notas, chat educativo y seguimiento de progreso e intentos.

Arquitectura

Frontend Next.js 14 (App Router) con React 18 que consume la API REST de Klerk. Estado servidor con TanStack Query, formularios con react-hook-form + Zod, Markdown + KaTeX para contenido educativo, streaming SSE para el chat.

Navegador (Next.js 14 App Router, React 18)
   │  react-hook-form + Zod · TanStack Query · next-themes
   │  react-markdown + KaTeX + highlight.js · Recharts (progreso)
   ▼
Klerk API (NestJS) ── JWT + x-api-key ── PostgreSQL / Gemini / SMTP
   ▲
Vercel (learnyos.vercel.app)

Next.js 14 con App Router: páginas de exámenes, flashcards, notas, chat, comunidad y estadísticas. Estado servidor con TanStack Query para caché y revalidación.
Formularios tipados con react-hook-form + Zod + @hookform/resolvers; UI con Radix UI + Tailwind CSS 3 + sonner/vaul para feedback.
Contenido educativo renderizado con react-markdown + remark-gfm/math + rehype-katex/highlight: soporta tablas, fórmulas y código.
Chat educativo con streaming SSE (EventSource) contra POST /messages/send/stream; exámenes jugables con intentos registrados en /exam-attempts.

Stack detallado

Capa	Tecnología	Detalle
Framework	`Next.js 14 / React 18`	App Router, SSR/SSG donde conviene, resto CSR contra la API
Estado servidor	`TanStack Query 5`	Caché de exámenes, mazos, notas, créditos y chat
Formularios	`react-hook-form + Zod`	Validación tipada antes de llamar a Klerk
UI	`Radix UI + Tailwind 3`	Accordion, dialog, tabs, toast, command palette (cmdk)
Contenido	`Markdown + KaTeX + highlight.js`	Notas y preguntas con fórmulas y código
Gráficas	`Recharts`	Progreso e historial de intentos
Backend	`Klerk (NestJS + PostgreSQL)`	Ver ficha /proyecto/klerk

Datos y conexiones

El frontend no tiene BD propia: todo el dominio (User, Exam → Question → Option, Card → FlashCard, Note → NoteContent, Chat → Message, DailyCredits, Likes, ExamAttempt) vive en PostgreSQL vía Klerk.
Comparte códigos de 5 caracteres para contenido público (/exams/code/:code); likes polimórficos y chat global para comunidad.

Autenticación y seguridad

Login email/contraseña, Google OAuth y modo invitado; el backend devuelve accessToken (24h) + refreshToken hasheado.
Cada request lleva x-api-key global + Authorization: Bearer JWT; el frontend guarda el token y el rol para gating de rutas.

Frontend y rutas

/ (home)
/exams, /exams/play/:id, /exams/code/:code
/flash-cards, /flash-cards/code/:code
/notes, /notes/code/:code
/chat (streaming SSE)
/comunidad, /estadísticas, /créditos

Generación por tema o archivo: el frontend sube a Klerk y muestra skeleton + polling/stream hasta tener el JSON estructurado.
Reproductor de exámenes con temporizador, corrección inmediata y registro de intento para estadísticas.

Despliegue

Dónde: Vercel (learnyos.vercel.app) · API Klerk separada · PostgreSQL gestionado (Aiven/Neon)

Build: next build; env con NEXT_PUBLIC_API_URL + API_KEY pública de lectura
CORS_ORIGINS en Klerk debe incluir el dominio Vercel
Preview deployments por PR para probar integración antes de merge

Metodología y decisiones

Desarrollo iterativo por features educativas: primero exámenes quiz, luego ICFES, flashcards, notas y chat.
Contrato API-first: los DTOs de Klerk (GenerateExamDto, etc.) dictan los schemas Zod del frontend; si el backend rechaza (400 array), se muestra tal cual.
Verificación con pnpm build + ESLint (next lint) antes de cada push; revisión manual del streaming SSE con throttling de red.

Retos y soluciones

Renderizar IA impredecibleJsonExtractor en backend + sanitización XSS en frontend; si el JSON viene con fences markdown se limpia antes de renderizar.

Costos de IACréditos diarios (30/día) visibles en UI (/credits/status); rate-limit por generación reflejado con mensajes y retry.

Qué aprendí

App Router + React Server Components vs. componentes cliente para Markdown/KaTeX.
Diseño de UX para generación asíncrona larga (optimistic UI + SSE).
Integración frontend-backend con doble capa de auth (API key + JWT).

Ejecutar en local

git clone https://github.com/xenoxf/learnyos-x2 && cd learnyos-x2
pnpm install (o npm install)
Crear .env.local con NEXT_PUBLIC_API_URL=http://localhost:2300 y la x-api-key de Klerk
pnpm dev → http://localhost:3000 (requiere Klerk corriendo)

Próximos pasos

Modo offline con Service Workers para repasar sin conexión.
Spaced repetition real en flashcards.
Exportar exámenes a PDF.

↗