Mobile-First · Zero UI Libraries · PWA Instalable · Offline-Ready
Explorador y reproductor musical de alto rendimiento impulsado por Apple iTunes Search API y LRCLIB.
🌐 Ver Aplicación en Vivo (GitHub Pages)
¿Qué es? · Enfoque · Funcionalidades · Inspiración · Instalación · Arquitectura · Autor · Licencia
MusicSearchApp es una Progressive Web App (PWA) desarrollada para el Trabajo Integrador — Módulo 1 de la materia Aplicaciones Móviles (2026).
La plataforma permite explorar en tiempo real el catálogo musical internacional, escuchar vistas previas de audio de 30 segundos, consultar fichas técnicas con portadas en alta definición, leer letras de canciones sincronizadas o en texto plano, gestionar una lista de deseos personalizada con validaciones estrictas y registrar el historial de navegación, con funcionamiento garantizado tanto online como offline.
El desarrollo del trabajo integrador se fundamentó en las siguientes decisiones y enfoques técnicos:
- Filosofía "Zero UI Libraries": Todo el maquetado y los estilos visuales fueron construidos artesanalmente utilizando CSS Modules y un sistema de variables CSS centralizado (
variables.css). Se evitó intencionalmente el uso de frameworks prefabricados (Tailwind, Bootstrap o UI kits) para garantizar el dominio pleno de CSS Grid, Flexbox y maquetación nativa sin estilos en línea. - Diseño Mobile-First: La interfaz se concibió partiendo de la ergonomía en teléfonos celulares, asegurando áreas táctiles confortables (mínimo 44×44 px), navegación accesible con una sola mano y una escala de 4 breakpoints adaptativos hasta pantallas de escritorio.
- Tipado Estricto de Datos: Con TypeScript 5.5 en modo estricto, se definieron contratos e interfaces rigurosas para cada modelo de datos (canciones, álbumes, artistas, letras y preferencias), garantizando la integridad de las respuestas recibidas desde las APIs externas y previniendo errores en tiempo de ejecución.
- Consumo Asíncrono y Resiliencia de Red: Integración con Fetch API nativo, estructurada en capas de servicio desacopladas y respaldada con
AbortControllerpara la cancelación automática de peticiones obsoletas durante la búsqueda en tiempo real. - Arquitectura Orientada a la Experiencia Offline: Implementación de un Service Worker nativo con estrategias de caché del App Shell y almacenamiento local con
localStorage, asegurando que la Lista de Deseos y el Historial permanezcan completamente funcionales ante la pérdida de conexión a internet.
- Búsqueda Avanzada en Vivo: Consultas directas a la API de Apple iTunes con filtros por término, artista, álbum, catálogo de 22 géneros y 4 criterios de ordenamiento, optimizadas con debounce y cancelación de peticiones obsoletas.
- Ficha Técnica & Audio Player: Visualización de portadas en HD (500x500), metadatos enriquecidos (ISRC, año, duración) y reproductor local de audio preview de 30 segundos.
- Letras Sincronizadas y Planas: Integración dual con el servicio abierto LRCLIB para alternar entre letras en texto plano y sincronizadas línea por línea en tiempo real.
- Lista de Deseos: Formulario modal con validación dinámica (prioridad 1 a 5, categoría obligatoria y notas personales de hasta 200 caracteres), filtrado reactivo y persistencia en
localStorage. - Historial Cronológico Inverso: Registro automático de canciones visitadas sin duplicados, cálculo de tiempo transcurrido relativo ("hace 5 minutos") y vaciado rápido.
- PWA & Modo Offline: Instalación como aplicación nativa en celulares y computadoras (WebAPK/Standalone), carga instantánea desde
CacheStoragey banner visual de aviso ante desconexión. - Contacto & Geolocalización: Perfil institucional del equipo desarrollador, formulario validado y mapa interactivo embebido con OpenStreetMap centrado en la Catedral de La Plata.
- MotherDuck (Diseño de Arte Neo-Brutalism): Inspiración para la paleta cromática beige editorial (
#F4EFEA), bordes carbón de alto contraste (#121212), sombras planas sólidas (box-shadow: 4px 4px 0 #121212) y tipografía. - Its Hover (Logo): Referencia para el componente interactivo
VinylIcon, simulando el giro analógico del vinilo, la aguja fonocaptora y el pulso rítmico. - Apple Music Web & Spotify Web (Arquitectura de Reproductor): Modelo para la diagramación de metadatos de audio y el reproductor persistente con barra de reproducción continua.
- LRCLIB.net (Catalogo Open Source de Letras): Base de datos abierta comunitaria para la visualización de letras musicales.
- OpenStreetMap (Mapa Open Source): Solución comunitaria de mapas abiertos sin dependencias de APIs propietarias.
# 1. Clonar el repositorio
git clone https://github.com/soydiegodev/MusicSearch-APP.git
cd MusicSearch-APP
# 2. Instalar dependencias
pnpm install
# 3. Iniciar el servidor de desarrollo
pnpm dev
# 4. Compilar para producción (genera la carpeta /dist con la PWA lista)
pnpm build
# 5. Previsualizar la versión de producción optimizada
pnpm previewEl código fuente sigue el patrón Vertical Slice Architecture, organizando la solución en módulos de negocio verticales.:
src/
├── components/ # Componentes visuales transversales y reutilizables
│ ├── common/ # Botones, Cards, Modales, Skeleton loaders, Íconos SVG
│ └── layout/ # Navbar, RootLayout, OfflineBanner, Footer
├── context/ # Estado global con React Context (Audio Player, Wishlist)
├── features/ # Módulos verticales autocontenidos por funcionalidad
│ ├── home/ # Portada temática, Hero y canciones destacadas
│ ├── search/ # Barra de búsqueda, filtros dinámicos y paginación
│ ├── detail/ # Ficha técnica, reproductor local y visor de letras LRCLIB
│ ├── wishlist/ # Formulario modal de preferencias, listado y filtros
│ ├── history/ # Historial cronológico inverso de navegación
│ └── contact/ # Perfil institucional y mapa interactivo OpenStreetMap
├── hooks/ # Custom hooks genéricos (useLocalStorage, useOnlineStatus)
├── pages/ # Páginas contenedoras de rutas montadas en react-router
├── routes/ # Configuración y definición de rutas (react-router-dom v7)
├── services/ # Clientes HTTP desacoplados (itunesService, lrclibService)
├── styles/ # Design Tokens (variables.css con paleta MotherDuck, globals.css)
└── utils/ # Funciones puras de utilidad (formateadores, cálculo de tiempo)
- Diego Montaño — @soydiegodev
Proyecto desarrollado para el Trabajo Integrador — Módulo 1 (Aplicaciones Móviles, 2026).
Este proyecto está bajo la Licencia MIT — consulta el archivo LICENSE para más detalles.