edueasy/PLAN.md

EduEasy — Plan de Plataforma

Arquitectura General

Plataforma educativa para una nena de 8 años con déficit de atención, baja abstractividad, que no sabe leer ni contar (bases malas en 1er grado). Dos caras en un mismo server:

App	Dominio	Dispositivo	Usuario
Aprendizaje	mate.cbcren.online	iPad Air 4 (solo dedo)	La nena
Dashboard	simulacro.cbcren.online	Poco F6 Pro	La mamá

Stack: Next.js 15 + React 19 + TypeScript estricto + Tailwind CSS + shadcn/ui + Better Auth + Prisma + PostgreSQL + ts-fsrs
Deploy: All-in-one Docker (un proceso Next.js + Postgres) en red caddy del server existente (194.163.191.200)

Decisiones de Diseño Cerradas

Decisión	Respuesta
Mascota	🐱 Gato — guía las sesiones con instrucciones en audio, celebra logros, da feedback en errorless learning. Sin nombre fijo aún.
Paleta	Calmada — fondo #FFF8F0 crema/beige, primario #8CB8A0 verde salvia, secundario #6B8FA3 azul medio, acento #D4A574 terracota, texto #2D3436 (no negro puro). Bajas saturaciones en todos.
Audio	TTS por ahora (Web Speech API, voz es-ES femenina). Se reemplaza por grabaciones reales es-AR en Fase 4+ cuando el contenido esté validado.

---

Pedagogía (Métodos Europeos)

Área	Método	Aplicación
Lectura	Borel-Maisonny (FR)	Cada fonema tiene un gesto físico + sonido. La nena hace el gesto en el aire + traza con el dedo en la pantalla + escucha el audio.
Lectura	Jolly Phonics (UK) adaptado	Orden de aprendizaje: no A-B-C, sino por frecuencia de uso. Vocales primero (A, E, I, O, U) + consonantes sonoras continuas (S, M, L, N).
Lectura	Método silábico	Español = 5 vocales puras, sílabas CV, CVC, CCV. Silabeo sistemático desde el día 1.
Numeración	CPA (Concrete-Pictórico-Abstracto)	Concreto: objetos (tapitas virtuales para contar). Pictórico: dibujos de objetos. Abstracto: el número símbolo.
Numeración	Regletas Cuisenaire (Bélgica)	Cantidad como barra de color. 1=blanco, 2=rojo, 3=verde claro... La nena ve y toca la cantidad sin "contar" abstractamente.
Internalización	Galperin (URSS)	1. Mano: manipular objetos. 2. Voz externa: decir en voz alta. 3. Voz interna: susurrar. 4. Mental: hacerlo en la cabeza.
Errores	Errorless learning	Nunca se muestra "incorrecto". Si titubea, el sistema da la pista más obvia (modelado). Si persiste el error, fadea la ayuda.
Refuerzo	Fijo y predecible	Sin slots, sin FOMO, sin rachas ansiosas. Estrellita predecible después de cada ronda completa.
Sesiones	Chunking estructurado	10-15 min máximo. Temporizador visual tipo Time Timer. Micro-pausa motora cada 5 min (saltar, aplaudir).

---

Stack Técnico

Frontend:  Next.js 15 (App Router) + React 19 + TypeScript + Tailwind CSS
UI Lib:    shadcn/ui (componentes base)
Auth:      Better Auth (login mamá + QR pairing → JWT device-bound para nena)
DB:        PostgreSQL + Prisma ORM
Spaced Rep: ts-fsrs (Free Spaced Repetition Scheduler)
Canvas:    perfect-freehand (trazo con dedo) + @use-gesture/react
Audio:     Web Speech API (TTS es-ES/es-MX, confirmado: TTS por ahora → reemplazar con grabaciones reales es-AR en Fase 4+)
Animación: framer-motion (transiciones lentas 300-500ms, sin sparkles)
Charts:    Recharts (dashboard mamá)
Deploy:    Docker + red caddy existente

Repos reutilizados

• ts-fsrs (npm) — algoritmo FSRS de repetición espaciada
• perfect-freehand (npm) — trazado fluido con dedo (Excalidraw)
• Better Auth (npm) — auth + device pairing
• shadcn/ui (npm) — componentes base de UI
• Math Learning Center apps — referencia UX de manipulativos virtuales (number-rack, ten-frames)

---

Modelo de Datos

model Family { id, name, created_at }
model Parent { id, family_id, email, name, auth_provider }
model Child { id, family_id, name, avatar, birthdate, profile_notes }
model Device { id, child_id, device_fingerprint, paired_at, last_seen, role }
model Session { id, child_id, started_at, ended_at, duration_sec, skills_practiced }
model SkillAttempt { id, session_id, skill_code, prompt_level, correct, response_ms }
model FsrsCard { id, child_id, skill_code, due_at, stability, difficulty, reps, lapses }
model Milestone { id, child_id, skill_code, reached_at }

---

Estructura del Proyecto

/home/ren/edueasy/
├── app/
│   ├── globals.css
│   ├── layout.tsx               # Raíz (fonts, metadata)
│   ├── page.tsx                 # Redirige según host
│   ├── child/                   # mate.cbcren.online
│   │   ├── layout.tsx           # Layout infantil (gato, audio siempre presente)
│   │   ├── page.tsx             # Menú principal de la nena
│   │   ├── sesion/
│   │   └── logros/
│   ├── parent/                  # simulacro.cbcren.online
│   │   ├── layout.tsx           # Layout dashboard + sidebar
│   │   ├── page.tsx             # Dashboard principal
│   │   ├── auth/login/
│   │   ├── auth/pairing/
│   │   └── configuracion/
│   └── api/
│       ├── auth/[...all]/       # Better Auth handler
│       ├── pairing/             # QR pairing endpoint
│       └── sessions/sync/       # Sync offline → server
├── components/
│   ├── ui/                      # shadcn/ui
│   ├── child/                   # Componentes de la nena
│   │   ├── gato-mascota
│   │   ├── trazo-letra (canvas tracing)
│   │   ├── vocal-card
│   │   ├── cuisenaire-rod
│   │   ├── temporizador-visual
│   │   └── boton-grande (60-80px)
│   └── parent/                  # Componentes del dashboard
├── lib/
│   ├── db.ts (Prisma client)
│   ├── auth.ts (Better Auth server)
│   ├── auth-client.ts
│   ├── speech.ts (Web Speech API)
│   ├── fsrs.ts (ts-fsrs wrapper)
│   └── pedagogia/
│       ├── borel-maisonny.ts (fonemas + gestos)
│       ├── cuisenaire.ts (regletas)
│       ├── errorless.ts (prompt fading)
│       └── cpa-progression.ts (CPA estados)
├── prisma/schema.prisma
├── middleware.ts (host-based routing)
├── Dockerfile
├── docker-compose.yml
├── package.json
├── tsconfig.json
├── next.config.ts
├── tailwind.config.ts
├── postcss.config.js
├── components.json (shadcn/ui)
└── .env.local

---

UX Constraints (iPad Air 4 + Dedo)

• Touch targets: 60–80px mínimo (baselines adultos 44px no alcanzan para niños)
• Drag > Tap para interacciones principales
• Una sola acción focal por pantalla
• 100% iconografía + audio (la nena NO LEE)
• Sin "X roja" nunca — sonido neutro + mascota dice "probemos juntas"
• Fondo claro baja saturación (crema/beige) + acentos verde salvia + azul medio
• Botón "Tocá para empezar" en cada sesión (unlock AudioContext en iOS Safari)
• Persistencia al backend siempre (Safari evicta IndexedDB a 7 días)

iOS Safari Técnico

• Audio: .m4a primario + .mp3 fallback. NUNCA .ogg.
• AudioContext: requiere user gesture para desbloquear.
• 100dvh en vez de 100vh (barra de Safari).
• touch-action: manipulation para eliminar delay 300ms.
• inputs con font-size: 16px mínimo (evita zoom automático).

---

Roadmap

Fase 0 — Fundaciones (1-2 sem)

• Repositorio + package.json + configs
• Docker + docker-compose
• Prisma schema + migración
• Better Auth + QR pairing
• Design system base (gato mascota, paleta, component primitives)
• Caddy config update

Fase 1 — Lectura MVP

• Módulo vocales: A, E, I, O, U
• Audio TTS para cada fonema + palabra ejemplo
• Gesto Borel-Maisonny (animación + instrucción)
• Trazo con dedo (canvas + perfect-freehand)
• Sesión guiada 10 min + temporizador visual
• Errorless learning + fading automático
• Logros por vocal completada

Fase 2 — Numeración MVP

• Módulo cantidades 1-5 (expandir a 10)
• CPA: objetos → imagen → símbolo
• Regletas Cuisenaire virtuales (arrastrar, comparar)
• Conteo one-to-one con arrastre
• Galperin: mano → voz → cabeza

Fase 3 — Adaptativo + Dashboard

• ts-fsrs: repaso espaciado por skill
• Dashboard mamá: streak, tiempo, mastery %, último resumen
• Push notifications al Poco F6 Pro
• QR pairing funcional
• Export de progreso

Fase 4+ (futuro)

• Consonantes y sílabas completas
• Números 11-100, suma/resta
• Grabaciones de audio real (es-AR)
• IA adaptativa (Ollama/Open WebUI)

---

Diseño Visual

Mascota: 🐱 Gato (sin nombre definido — que la nena lo nombre).

• Guía las sesiones, da instrucciones en audio, celebra logros.
• Animaciones suaves (no bruscas), tamaño grande en pantalla.

Paleta:

• Fondo: #FFF8F0 (crema suave)
• Primario: #8CB8A0 (verde salvia)
• Secundario: #6B8FA3 (azul medio)
• Acento: #D4A574 (terracota suave)
• Texto: #2D3436 (gris oscuro, no negro puro)
• Correcto: #7FB685 (verde suave, no brillante)

Tipografía:

• Títulos: Fredoka One (redondeada, amigable, legible)
• Interface: Inter (sistema, para dashboard de la mamá)
• La nena no ve texto — solo escucha. Las letras aparecen grandes, claras, bien trazadas.

---