ENTER

DOC_TECNICA.md

1. Introducción

Kipu Music Pro es un sistema de base de datos y catálogo musical de alto rendimiento, diseñado con una estética "Cybertech/Glassmorphism". El proyecto utiliza **Next.js 15**, **TypeScript**, **Zustand** para la gestión de estado y **Supabase** como infraestructura de datos principal.

2. Arquitectura del Proyecto

2.1 Stack Tecnológico

  • Frontend: Next.js 15 (App Router), React 19.
  • Estilos: Tailwind CSS 4, Framer Motion (para animaciones HUD).
  • Estado Global: Zustand con persistencia en LocalStorage.
  • Backend & DB: Supabase (PostgreSQL, Realtime, Storage).
  • Iconografía: Lucide React.
  • Validación Forense: Integración de metadatos técnicos (BPM, Key, Model Info).

2.2 Estructura de Directorios

  • src/app/: Rutas principales y páginas.
    • admin/: Portal de administración seguro.
    • api/: Endpoints de backend (autenticación, gestión de datos).
    • playlists/: Gestión dinámica de listas de reproducción.
  • src/components/: Componentes reutilizables.
    • player/: Lógica y UI del reproductor persistente.
    • catalog/: Visualización de tracks (TrackCard, TrackGrid).
    • admin/: Consola técnica y editores de estado.
  • src/store/: usePlayerStore.ts - El cerebro de la aplicación.
  • src/lib/: Configuración de Supabase y utilidades de sistema.

3. Funcionalidades Core

3.1 Gestión de Audio y Reproductor

El reproductor es un componente persistente (PersistentPlayer) que mantiene el estado de audio a través de la navegación.

  • Cola de reproducción: Maneja pistas dinámicamente desde cualquier lista.
  • Modos: Loop, Shuffle y control de volumen.
  • Visualización: Sincronización de metadatos en tiempo real.

3.2 Sistema de Favoritos y Playlists

Sincronización híbrida (Local + Cloud):

  • Likes: Los usuarios pueden marcar favoritos que se sincronizan con Supabase.
  • Playlists: Creación, edición y eliminación de listas personalizadas.
  • Sincronización Directa: Las acciones de biblioteca impactan inmediatamente en la base de datos si el usuario está autenticado.

3.3 Notificaciones (Toast System)

Un sistema de feedback global animado que reemplaza los alerts nativos.

  • Animaciones: Entrada y salida fluida con framer-motion.
  • Contexto: Feedback específico para éxitos, errores e información.

4. Panel de Administración (Cyber Console)

4.1 Clip Manager Console (Forensics UI)

Diseñado para técnicos y administradores de contenido:

  • Vista de Nodo: Cada clip se trata como un "Nodo" con ID único.
  • Filtros Avanzados: Búsqueda por ID (UUID) o nombre, filtrado por estado (Online/Draft).
  • Metadata Técnica: Visualización de BPM, Key y Versión del Modelo de IA.
  • Impact_Matrix: Gráfico dinámico de rendimiento por pista.

4.2 Seguridad

  • Backend Auth: Login validado mediante una API interna (/api/admin/login).
  • Secretos: Las credenciales se gestionan exclusivamente en el servidor mediante variables de entorno en .env.local, protegiendo el acceso contra inspecciones de código.

5. Base de Datos (Supabase Schema)

  • clips: Almacena las pistas de audio, URLs de imagen, metadatos y estado de publicación.
  • user_likes: Relación entre usuarios y tracks favoritos.
  • playlists: Cabeceras de listas de reproducción del usuario.
  • playlist_clips: Tabla pivot para la relación canción-playlist, incluyendo el orden (position).

6. Guía de Desarrollo

6.1 Instalación

npm install

6.2 Variables de Entorno (.env.local)

NEXT_PUBLIC_SUPABASE_URL=tu_url NEXT_PUBLIC_SUPABASE_ANON_KEY=tu_key ADMIN_USERNAME=admin ADMIN_PASSWORD=tu_password

6.3 Ejecución

npm run dev

7. Filosofía de Diseño

El proyecto prioriza la **Velocidad de Interacción** y la **Estética Premium**. Se utilizan efectos de Glassmorphism (desenfoque de fondo), gradientes de malla animados y una tipografía monospaciada en áreas técnicas para transmitir una sensación de sistema avanzado de alta fidelidad.