reaktor/producto.md

Reaktor — Product Document

Vision

Reaktor es una plataforma web de sintesis modular que combina un sandbox creativo con un sistema de aprendizaje gamificado (SynthQuest). La plataforma permitira a los usuarios crear, aprender, compartir y descubrir sonidos sintetizados.

---

Producto Actual (v1 — Live)

Sandbox Mode

• Sintetizador modular completo en el navegador (Tone.js)
• 15+ tipos de modulos: Oscillator, Filter, Envelope, VCA, LFO, Mixer, Sequencer, Piano Roll, Keyboard, Drum Pad, CV→Gate, Delay, Reverb, Distortion, Scope, Output, Noise
• Conexion visual de modulos con cables de audio/control/trigger
• Canvas con zoom, pan, grid
• Guardado/carga de presets (localStorage)
• Export/import de patches como JSON
• Demo Chiptune incluido

SynthQuest (Game Mode)

• 12 mundos tematicos, 96 niveles progresivos
• Sistema de 3 estrellas por nivel
• Hints con penalizacion (max 2 estrellas)
• Boss levels por mundo
• Progreso persistente (localStorage)

Mobile

• UI responsiva completa (bottom sheet, tab bar, touch panning, pinch zoom)
• Keyboard y Drum Pad a pantalla completa
• PWA instalable

---

Roadmap

Phase 0 — Estructura (monorepo)

Objetivo: Preparar la base tecnica para el backend sin romper nada.

• Reestructurar a monorepo (packages/client + packages/server)
• Actualizar Dockerfile (multi-stage: client build + server)
• Docker Compose con PostgreSQL
• Verificar que deploy funciona igual que antes

Phase 1 — Usuarios y Auth

Objetivo: Sistema de cuentas de usuario.

• Backend API (Fastify + PostgreSQL + Drizzle ORM)
• Registro por email + password (argon2)
• Login con JWT (access token 15min + refresh cookie 30d)
• Perfil de usuario (username, avatar, bio)
• Roles: user, premium, admin
• UI: modal de login/registro en el frontend
• Auth context en React (user, isLoggedIn, role)
• OAuth con Google/GitHub (opcional, puede ir en Phase 1.5)

Phase 2 — Sincronizacion de Datos

Objetivo: Los datos del usuario viajan con su cuenta, no con el dispositivo.

• Sync de presets a la nube (offline-first, localStorage primary)
• Sync de progreso de SynthQuest
• Merge inteligente: last-write-wins por timestamp
• Cola de sincronizacion offline (flush al reconectar)
• Multi-dispositivo: login en otro dispositivo y tener todo

Phase 3 — Workshop / Comunidad

Objetivo: Compartir creaciones y descubrir sonidos de otros usuarios.

• Publicar patches con titulo, descripcion, tags
• Preview de audio (generado client-side con Tone.js Recorder)
• Galeria publica: buscar, filtrar por tags, ordenar (popular/reciente)
• Sistema de likes/favoritos
• Cargar patch compartido directamente en el Sandbox
• Perfil publico de usuario con sus patches compartidos
• Comentarios en patches (v2, opcional)

Phase 4 — Panel de Administracion

Objetivo: Control total sobre la plataforma.

• Dashboard con KPIs:
  • Usuarios totales, DAU, MAU
  • Patches compartidos (total, por dia)
  • Usuarios premium vs free
  • Niveles completados (metricas del juego)
• Gestion de usuarios:
  • Lista, busqueda, filtros
  • Ver detalle de usuario (patches, progreso, rol)
  • Cambiar rol (user → premium → admin)
  • Banear/desbanear
• Moderacion del Workshop:
  • Ver patches reportados/flagged
  • Eliminar contenido (soft delete)
  • Editar titulo/descripcion
  • Ver historial de moderacion

Phase 5 — Monetizacion (futuro)

Objetivo: Cursos premium y sostenibilidad.

• Definir proveedor de pagos (Stripe, LemonSqueezy, Paddle)
• Plan Premium: acceso a cursos avanzados de sintesis
• Checkout flow
• Gestion de suscripciones (portal del usuario)
• Metricas de revenue en admin dashboard
• Sandbox permanece gratuito

Phase 6 — Cursos (futuro)

Objetivo: Contenido educativo estructurado de pago.

• Sistema de cursos con lecciones
• Lecciones interactivas (como SynthQuest pero mas profundo)
• Certificados de completado
• Tracks tematicos: "Sound Design", "Beat Making", "Ambient Textures"

---

Stack Tecnico

Capa	Tecnologia
Frontend	React 18, Vite, Tone.js
Backend	Fastify v5 (Node.js)
Base de datos	PostgreSQL 16 + Drizzle ORM
Auth	JWT + httpOnly refresh cookies + argon2
Storage	Filesystem (Docker volume)
Deploy	Docker + Docker Compose
Hosting	montlab.dev (self-hosted)
Git	Gitea (git.montlab.dev)

---

Principios de Diseno

1. Offline-first — La app funciona sin internet. El backend es un extra, no una dependencia.
2. Opt-in — Todo funciona sin cuenta. Login desbloquea sync + comunidad.
3. Mobile-first — Cada feature se disena primero para movil.
4. Progresivo — Cada phase se puede deployar independientemente.
5. Simple — Preferir soluciones simples sobre arquitecturas complejas.

---

Metricas de Exito

• Phase 1: 100 usuarios registrados en el primer mes
• Phase 3: 50 patches compartidos en el Workshop
• Phase 5: 10 suscriptores premium
• Long-term: Reaktor como referencia en educacion de sintesis modular web

---

Notas Tecnicas

SynthQuest: Niveles base vs niveles custom

Los 96 niveles base (12 mundos × 8 niveles) estan hardcoded en ficheros JS (packages/client/src/game/levels/world1.js ... world12.js). Estos niveles no se pueden editar desde el admin panel porque contienen funciones test() en JavaScript que validan si el jugador ha completado el objetivo:

checks: [
  {
    star: 1,
    desc: 'Conecta el oscilador a la salida',
    test: (mods, conns) => {
      // Logica JS que inspecciona los modulos y conexiones
      return conns.some(c => c.from.moduleId === osc.id && ...);
    },
  },
]

Estas funciones test() no se pueden serializar en una base de datos — son codigo ejecutable que depende del contexto del engine. Para editar los niveles base hay que modificar directamente los ficheros JS y hacer deploy.

Los niveles custom creados desde el admin panel se almacenan en PostgreSQL y permiten definir titulo, descripcion, modulos disponibles y patch base (importado del Sandbox). Sin embargo, no soportan checks/objetivos custom porque requeririan escribir funciones JS. Los niveles custom se pueden usar para:

• Tutoriales simples tipo "monta este circuito"
• Challenges de la comunidad
• Contenido adicional sin sistema de estrellas

Para añadir niveles con sistema de estrellas completo, hay que crear un fichero worldN.js con los checks en JS.

---

Documento vivo — actualizar conforme avanza el desarrollo.