ENTER

DOC_TECNICA.md

1. Introducción

Apurímac 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 **Turso (libSQL)** 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: Turso (libSQL distribuido sobre SQLite).
  • 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 Turso (`turso.ts`), `auth.ts` (JWT), `schema.sql` 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 visitantes pueden marcar favoritos. Se persisten en el navegador (localStorage) ya que no hay login de usuarios finales.
  • Playlists: Creación, edición y eliminación de listas personalizadas (también localStorage).
  • Sincronización directa con Turso: `play_count` y `upvote_count` se actualizan directamente en la base al reproducir un track.

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 (Turso / libSQL 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)

TURSO_DATABASE_URL=libsql://... TURSO_AUTH_TOKEN=tu_token ADMIN_USERNAME=admin ADMIN_PASSWORD=tu_password JWT_SECRET=una_cadena_aleatoria_larga

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.