# 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

```prisma
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)
- [x] Repositorio + package.json + configs
- [x] Docker + docker-compose
- [x] Prisma schema + migración
- [x] Better Auth + QR pairing
- [x] Design system base (gato mascota, paleta, component primitives)
- [x] 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.

---