acbe4257ae
The 96 base levels have JavaScript test() functions in their checks that validate gameplay objectives. These can't be serialized to a database — they need to stay as code. Custom levels from admin panel work for tutorials/challenges but without the star check system. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
181 lines
6.6 KiB
Markdown
181 lines
6.6 KiB
Markdown
# 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:
|
||
|
||
```javascript
|
||
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.*
|