Eduka
Plataforma educativa abierta con IA para estudiantes de colegio público en Costa Rica (MVP: III Ciclo — 7.º, 8.º y 9.º).
Antes se llamaba Edukemonos; la mascota y tutor, Kemo, conserva el nombre original. Guía de marca: docs/brand.md.
Eduka es una iniciativa independiente. No es una plataforma oficial del Ministerio de Educación Pública.
Estructura
apps/web Next.js 16 (App Router, TS), Tailwind v4 + shadcn/ui
packages/ai Capa de IA intercambiable (Anthropic / OpenAI), registro de uso, prompts versionados
packages/curriculum Tipos y esquema del manifiesto de fuentes
scripts/ingest Programas de estudio oficiales del MEP: manifiesto (sources.json), descarga respetuosa, verificación
supabase/migrations Esquema, funciones y RLS
supabase/tests Pruebas de RLS contra Postgres (intentan romper cada política)
config/ help-resources.json (lo completa el fundador con números verificados)
Requisitos
- Node 22+ y pnpm 10 (
corepack enable)
- Postgres 16 local para las pruebas de RLS (o cualquier URL de superusuario en
TEST_DATABASE_URL)
Instalación
pnpm install
cp .env.example apps/web/.env.local # complete los valores
pnpm dev # http://localhost:3000
Variables de entorno
Todas están documentadas en .env.example. Lo importante:
| Variable | Para qué |
|---|
NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY | Cliente de Supabase en el navegador |
SUPABASE_SERVICE_ROLE_KEY | Solo servidor y scripts. Nunca en el navegador |
AI_PROVIDER | anthropic u openai |
ANTHROPIC_API_KEY | Clave de Anthropic. En sesiones de Claude Code en la nube use EDUKEMONOS_ANTHROPIC_API_KEY: la plataforma retira ANTHROPIC_API_KEY del entorno |
MODEL_BULK, MODEL_TUTOR, MODEL_VERIFY | Identificadores de modelo. No están en el código: tómelos de la documentación vigente del proveedor |
AI_PRICES_JSON | Precios por modelo para estimar costos en ai_usage |
RETENTION_DAYS_CHAT | Días que se guardan las conversaciones con el tutor (30 por defecto; pendiente de revisión legal). Las borra cada día /api/cron/purge |
CRON_SECRET | Secreto de Vercel Cron para /api/cron/purge; sin él, la limpieza diaria no corre |
Pruebas
eval "$(supabase/tests/start-local-pg.sh)" # Postgres desechable en el puerto 54329
pnpm lint && pnpm typecheck && pnpm test
pnpm test:rls corre solo las pruebas de RLS. Crean una base nueva, aplican un shim mínimo de Supabase (supabase/tests/supabase-shim.sql: roles anon/authenticated/service_role, auth.uid()), todas las migraciones y la semilla, y luego actúan como cada rol.
Base de datos (Supabase)
pnpm exec supabase link --project-ref <ref>
pnpm exec supabase db push # aplica supabase/migrations
psql "$DATABASE_URL" -f supabase/seed.sql
Después de crear su cuenta de correo en la app, conviértase en admin desde el SQL editor:
update public.profiles set role = 'admin' where id = '<su user id>';
Puntos de diseño:
- Ciclo, grado y materia son datos (
cycles, grades, subjects): sumar I/II Ciclo es insertar filas.
- Los estudiantes son usuarios anónimos de Supabase; se unen a una sección con
join_section(código, nombre, consentimiento).
- Las respuestas correctas de los ítems no son legibles por la API; se califican en el servidor con
submit_attempt().
- Los docentes ven el tema de las sesiones del tutor, nunca la transcripción.
Despliegue (Vercel)
La app vive en apps/web dentro de un monorepo pnpm. En Project Settings → Build and Deployment:
| Ajuste | Valor |
|---|
| Root Directory | apps/web |
| Include files outside the root directory | Activado (por defecto) — necesario para el workspace |
| Framework Preset | Next.js (se detecta solo con el Root Directory correcto) |
| Install / Build / Output | Sin override |
| Node.js Version | 22.x |
Si Root Directory queda en la raíz del repo, Vercel no encuentra next en package.json, trata el proyecto como estático y falla con "No Output Directory named "public" found".
Variables de entorno: las de .env.example (las de Supabase e IA son necesarias a partir de la Fase 1; la página inicial no las usa).
Fuentes oficiales
pnpm sources:verify # comprueba que los 6 programas del manifiesto siguen disponibles
El cliente respeta robots.txt, se identifica y espera ~2,5 s entre peticiones al mismo dominio.
Ingesta del currículo (Fase 1)
Requiere pdftotext (poppler-utils) y las variables de Supabase e IA. Lee apps/web/.env.local si existe.
pnpm ingest db-check # ¿están las tablas?
pnpm ingest structure --source mep-prog-matematicas --grade 7 # muestra el costo estimado, NO gasta
pnpm ingest run --source mep-prog-matematicas --grade 7 --yes # descarga, extrae, estructura y carga
-
Extraer, no inventar: cada habilidad, contenido y extracto que propone la IA se verifica textualmente contra la página citada. Lo que no aparece queda marcado "por verificar" y la unidad no se puede publicar hasta corregirlo.
-
Todo entra como borrador. Volver a correr reemplaza los borradores de ese programa y grado, pero nunca toca unidades revisadas o publicadas.
-
pnpm ingest coverage … lista las páginas del grado que ninguna unidad cita, para revisarlas.
-
En Español el programa no trae habilidades específicas: sus criterios de evaluación se cargan como habilidades, cada uno con la página donde aparece textualmente.
Material de estudio e ítems (Fase 2)
Solo para unidades publicadas. Requiere la migración 20261003000100_content_generation.sql.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
