Instalacion

Guia para poner en marcha el proyecto MAMB en tu maquina local.

Requisitos previos

Software necesario

Verificar instalacion

node -v    # debe mostrar v18 o superior
psql --version
git --version

Clonar el repositorio

git clone https://github.com/risharddv/MAMBQ.git
cd MAMBQ

Configurar el backend

Variables de entorno

Crea un archivo .env en la carpeta backend/:

PORT=3000
DATABASE_URL=postgresql://usuario:contraseña@localhost:5432/mamb
JWT_SECRET=tu_clave_secreta_aqui
NODE_ENV=development

Descripcion de variables

Instalar dependencias

cd backend
npm install

Arrancar el servidor

npm run start

El servidor quedara disponible en http://localhost:3000.

Ejecutar el frontend

Con servidor local

El frontend es una SPA estatica que no necesita build ni dependencias adicionales:

cd frontend
npx http-server -p 8080

Abre http://localhost:8080 en tu navegador.

Sin servidor (modo rapido)

Tambien puedes abrir frontend/index.html directamente en el navegador.

Base de datos PostgreSQL

Crear la base de datos

Asegurate de tener PostgreSQL corriendo y crea la base de datos:

CREATE DATABASE mamb;

Creacion automatica de tablas

El backend crea las tablas automaticamente al arrancar si no existen. No necesitas ejecutar migraciones manualmente.

Verificar conexion

Puedes probar que la base de datos esta conectada visitando:

http://localhost:3000/api/health

Deberia responder:

{ "status": "ok", "museo": "MAMB", "db": "PostgreSQL" }

Instalar como PWA

En dispositivo movil

Una vez que la app este corriendo (local o en produccion):

1. Abre la app en Chrome o un navegador compatible
2. Busca el icono de instalacion en la barra de direcciones
3. Selecciona "Instalar" o "Anadir a pantalla de inicio"

En escritorio (Chrome)

1. Abre la app en Chrome
2. Haz clic en el icono de instalacion en la barra de URL
3. Confirma la instalacion

La app se instalara como aplicacion nativa en tu dispositivo.

Resolucion de problemas

El backend no arranca

• Verifica que PostgreSQL este corriendo
• Revisa que DATABASE_URL en .env sea correcta
• Asegurate de haber ejecutado npm install

La app no se conecta al backend

• Verifica que el backend este corriendo en el puerto correcto
• Revisa la consola del navegador para errores de CORS
• En modo local, el frontend debe apuntar a http://localhost:3000

Guia de uso

La aplicacion MAMB cuenta con 9 pantallas principales. A continuacion se describe cada una con su funcionalidad.

Inicio

Pantalla de bienvenida donde el visitante ingresa su nombre para comenzar la experiencia.

Elementos de la pantalla

• Campo de texto para ingresar nombre de visitante
• Accesos directos a la galeria y a subir una obra
• Carrusel de obras destacadas

Galeria

Vista principal con todas las obras del museo y de los visitantes.

Busqueda y filtros

• Buscar por titulo o nombre del artista
• Filtrar por tecnica artistica:
  • Oleo
  • Acuarela
  • Acrilico
  • Mixta
  • Escultura

Interacciones en la galeria

• Dar like a una obra con un toque
• Ver contador de likes acumulados
• Acceder al detalle completo de cada pieza

Subir obra

Formulario para que los visitantes publiquen su propia obra.

Pasos para subir

1. Selecciona o toma una fotografia de la obra
2. Ingresa titulo y descripcion
3. Selecciona la tecnica artistica
4. Elige un avatar y apodo de visitante
5. Envia el formulario

Moderacion automatica

El sistema filtra automaticamente nombres inapropiados antes de publicar, usando:

• Deteccion de leet-speak (ej: h4ck3r)
• Deteccion de homoglifos Unicode
• Lista de palabras prohibidas

Juego de memoria

Mini-juego de cartas con datos curiosos sobre pinturas famosas del MAMB.

Como jugar

1. Se muestran cartas boca abajo
2. Voltea dos cartas por turno
3. Encuentra los pares para desbloquear datos de cada obra
4. Completa el tablero para ganar

Objetivo educativo

Cada par desbloqueado revela informacion sobre una pintura famosa: autor, tecnica, ano y datos curiosos.

Perfil

Gestiona tu informacion de visitante.

Datos del perfil

• Apodo (nombre de usuario)
• Ciudad de origen
• Avatar seleccionado

Seleccion de avatar

8 opciones de avatar disponibles, generados con la API de DiceBear.

Historial de obras

Lista de todas las obras que el visitante ha subido a la plataforma.

Colecciones

Explora las colecciones permanentes del museo.

Organizacion

Las colecciones estan organizadas por sala o artista. Puedes guardar tus obras favoritas para acceder rapidamente.

Acerca del museo

Informacion sobre el Museo de Arte Moderno de Barranquilla.

Contenido

• Historia del museo
• Mision y vision cultural
• Equipo detras del proyecto
• Informacion de contacto

Detalle de obra

Vista expandida de una obra especifica.

Informacion mostrada

Sistema de interaccion

• Likes — contador de corazones acumulados
• Calificacion — promedio de estrellas (1-5)
• Boton calificar — permite asignar 1 a 5 estrellas

Autenticacion

Sistema de registro e inicio de sesion.

Registro

• Nombre de usuario (apodo)
• Ciudad
• Seleccion de avatar
• Contrasena

Inicio de sesion

• Login con apodo y contrasena
• Token JWT almacenado de forma segura

Sesion y offline

• Token con expiracion automatica
• Sincronizacion con localStorage para soporte offline
• Si el token expira, se solicita nuevo login

Landing Page

La landing page es el sitio web informativo del proyecto MAMB. Esta alojada en GitHub Pages y sirve como punto de entrada para que los visitantes conozcan el museo antes de acceder a la aplicacion principal.

URL: risharddv.github.io/MAMBQ

Proposito

La landing page cumple tres funciones principales:

Presentar el museo

Informacion sobre el MAMB, su mision cultural y su importancia para la comunidad artistica de Barranquilla.

Mostrar el proyecto

Descripcion de la aplicacion web, sus funcionalidades principales y las tecnologias utilizadas.

Redirigir a la app

Enlace directo a la PWA en mamb.online para que los visitantes accedan rapidamente.

Estructura del codigo

La landing se encuentra en la carpeta Landing MAMB/ del repositorio:

Archivos principales

Landing MAMB/
├── index.html    # Estructura HTML de la pagina
├── index.js      # Interacciones y animaciones
├── styles.css    # Estilos visuales
└── img/          # Imagenes y recursos graficos

Descripcion de archivos

Tecnologias

Despliegue

GitHub Pages

La landing se despliega automaticamente desde la rama main del repositorio mediante GitHub Pages. Cualquier cambio que se suba a main se refleja en produccion en minutos.

Configuracion en GitHub

1. Ve a Settings > Pages en el repositorio
2. Selecciona la rama main como source
3. La URL publica sera https://risharddv.github.io/MAMBQ/

Actualizaciones

Cada git push a la rama main actualiza automaticamente la landing page sin necesidad de configuracion adicional.

Despliegue en Render

La aplicacion MAMB (frontend + backend) esta desplegada en Render, una plataforma cloud con despliegue automatico desde GitHub.

URL de produccion: mamb.online (redirige a Render)

Arquitectura del despliegue

Servicio unificado

Render sirve tanto el frontend estatico como el backend Express desde un unico servicio. El servidor detecta si la peticion es para la API o para el frontend.

Diagrama de flujo

Cliente (navegador)
       |
       v
  mamb.online (Namecheap DNS)
       |
       v
  Render (Web Service)
       |
       |-- /api/*  --> Express (Node.js + PostgreSQL)
       +-- /*      --> Sirve frontend/index.html

Configuracion del servicio

Crear Web Service en Render

1. Entra a dashboard.render.com
2. Clic en New > Web Service
3. Conecta el repositorio de GitHub (risharddv/MAMBQ)

Parametros del servicio

Variables de entorno

En la seccion Environment del servicio:

PORT=10000
DATABASE_URL=postgresql://...
JWT_SECRET=tu_clave_secreta
NODE_ENV=production

Puerto dinamico

const PORT = process.env.PORT || 3000;
app.listen(PORT);

Despliegue automatico

Cada git push a la rama main dispara un nuevo despliegue automaticamente. Render ejecuta el build y arranca el servidor sin intervencion manual.

Dominio personalizado

Registro del dominio

Se adquirio el dominio mamb.online a traves de Namecheap.

Configuracion DNS

Este dominio redirige automaticamente al servicio alojado en Render, proporcionando una URL profesional y facil de recordar.

Flujo de redireccion

https://www.mamb.online/  -->  https://mamb-qsi0.onrender.com/

Plan gratuito — consideraciones

Limitaciones

Recomendaciones

Logs y monitoreo

Acceso a logs

Desde el dashboard de Render se accede a los logs en tiempo real del servicio.

Diagnostico de errores

Si el despliegue falla, el log muestra el error exacto del proceso de build o del arranque del servidor. Errores comunes:

• Variables de entorno faltantes
• Dependencias no instaladas
• Puerto ya en uso

Hoja de ruta — IA

Objetivo

Integrar un modelo de estilizacion artistica (Neural Style Transfer) que permita a los visitantes aplicar estilos de artistas reconocidos del MAMB a sus propias obras.

Flujo previsto

Proceso del usuario

1. El visitante sube una imagen de su obra
2. La imagen pasa por moderacion de contenido (ya implementada)
3. El visitante selecciona un estilo artistico
4. TensorFlow.js procesa la imagen
5. La imagen estilizada se publica en la galeria

Diagrama de flujo

Visitante sube imagen
        |
        v
  Moderacion de contenido (ya implementada)
        |
        v
  Seleccion de estilo artistico
  (ej: "estilo Obregon", "estilo Grau")
        |
        v
  TensorFlow.js aplica el estilo
        |
        v
  Imagen estilizada publicada en la galeria

Tecnologias planificadas

Modelo de IA

Almacenamiento

Estado actual del proyecto

Componentes implementados

Componentes pendientes

Requisitos para la implementacion

Modelos pre-entrenados

Seleccionar y optimizar modelos de style transfer para ejecucion en el navegador. Los modelos deben ser lo suficientemente ligeros para funcionar en dispositivos moviles.

Galeria de estilos

Recopilar obras de referencia de artistas del MAMB para usar como estilos base. Cada estilo necesita una imagen de referencia de alta calidad.

Infraestructura de almacenamiento

Definir servicio para persistir las imagenes procesadas. Las imagenes originales ya se almacenan en Render, pero las procesadas requieren almacenamiento adicional.

Vista general

MAMB sigue una arquitectura cliente-servidor con el frontend desacoplado del backend. Ambos se despliegan dentro del mismo servicio en Render.

Diagrama de componentes

Arquitectura completa

+-----------------------------------------------------+
|                   CLIENTE (PWA)                      |
|  index.html - app.js - style.css - manifest.json    |
|              Service Worker (sw.js)                  |
+-------------------------+---------------------------+
                          | HTTPS / REST JSON
+-------------------------v---------------------------+
|              BACKEND — Node.js + Express             |
|  /api/obras  /api/obras/:id  /api/health             |
|  JWT Auth - Helmet - CORS - Multer - Morgan          |
+-------------------------+---------------------------+
                          |
              +-----------v-----------+
              |      PostgreSQL       |
              |  obras | usuarios     |
              |  likes | ratings      |
              +-----------+-----------+
                          |
              +-----------v-----------+
              |   Render Disk         |
              |   /uploads (imagenes) |
              +-----------------------+

Capas del sistema

Flujo de peticiones

Consultar la galeria

1. El visitante abre la app y navega a la galeria
2. api.js envia GET /api/obras con parametros de busqueda/filtro
3. Express consulta PostgreSQL y devuelve las obras en JSON
4. app.js renderiza las tarjetas en el DOM
5. Si no hay conexion, se muestran obras guardadas en localStorage

Subir una obra

1. El visitante llena el formulario y selecciona una imagen
2. api.js envia POST /api/obras como multipart/form-data
3. Express valida el JWT y procesa la imagen con Multer
4. Se ejecuta moderacion de contenido sobre el apodo
5. La obra se guarda en PostgreSQL y la imagen en /uploads
6. Se devuelve la obra creada al cliente

Dar like a una obra

1. El visitante pulsa el boton de like
2. api.js envia POST /api/obras/:id/like
3. Express incrementa likes_count en PostgreSQL
4. Se devuelve el nuevo conteo al cliente

Calificar una obra

1. El visitante selecciona estrellas (1-5)
2. api.js envia POST /api/obras/:id/rate con el rating
3. Express suma al rating_total e incrementa rating_count
4. Se devuelve el nuevo total al cliente

Estructura del repositorio

Arbol de directorios

MAMBQ/
|-- frontend/
|   |-- index.html              # SPA — 9 pantallas
|   |-- app.js                  # Logica principal (1188 lineas)
|   |-- style.css               # Estilos mobile-first (2509 lineas)
|   |-- api.js                  # Cliente API REST con fallback offline
|   |-- usernameModeration.js   # Filtro de contenido
|   |-- manifest.json           # Configuracion PWA
|   +-- icons/                  # Iconos SVG 192x192, 512x512
|
|-- Landing MAMB/               # Landing estatica (GitHub Pages)
|   |-- index.html
|   |-- index.js
|   |-- styles.css
|   +-- img/
|
|-- backend/                    # API REST (Render)
|   |-- server.js               # Entry point del servidor
|   +-- uploads/                # Imagenes subidas por visitantes
|
|-- MAMB-docs/                  # Documentacion (Docusaurus)
|
|-- sw.js                       # Service Worker global
+-- readme.md                   # README del proyecto

Descripcion de carpetas

Comunicacion entre componentes

Tabla de comunicaciones

Seguridad en la comunicacion

• HTTPS obligatorio en produccion
• JWT para endpoints protegidos
• Helmet para headers de seguridad
• CORS configurado para origenes permitidos

Frontend

El frontend es una Single Page Application (SPA) desarrollada en JavaScript vanilla, sin frameworks. Es instalable como PWA y esta disenada con enfoque mobile-first.

Modulos principales

Tabla de archivos

index.html

Archivo HTML unico que contiene las 9 pantallas como secciones <section>. Solo una seccion es visible a la vez, controlada por CSS y JavaScript.

app.js

Modulo principal que maneja:

• Navegacion entre pantallas
• Renderizado de tarjetas de obras
• Logica del juego de memoria
• Gestion de perfiles y avatares
• Manejo de eventos de usuario

style.css

Estilos mobile-first con:

• Variables CSS para temas
• Grid y Flexbox para layout responsive
• Animaciones y transiciones
• Soporte para modo oscuro

api.js

Cliente HTTP que encapsula todas las llamadas al backend con fallback automatico a localStorage cuando no hay conexion.

Pantallas de la app

Tabla de pantallas

Navegacion SPA

Mecanismo de navegacion

No usa rutas del navegador. Cada pantalla es una seccion con display: none por defecto. app.js controla la visibilidad:

function showScreen(screenId) {
  document.querySelectorAll('.screen').forEach(s => s.classList.remove('active'));
  document.getElementById(screenId).classList.add('active');
}

Ventajas de este enfoque

• Sin dependencia de router externo
• Transiciones instantaneas entre pantallas
• Compatible con cualquier navegador
• Sin recarga de pagina

Cliente API (api.js)

Endpoints consumidos

Fallback offline

Cuando el backend no responde, api.js usa obras guardadas en localStorage bajo la clave mamb_local_obras, permitiendo navegar la galeria sin conexion.

Manejo de errores

El cliente captura errores de red y muestra mensajes apropiados al usuario. En caso de fallo, los datos se persisten localmente para sincronizar despues.

Service Worker

Estrategias de cache

Ciclo de vida

1. Instalacion — precachea assets criticos
2. Activacion — limpia caches antiguas
3. Fetch — intercepta peticiones y aplica estrategia segun tipo

PWA

Criterios de instalacion

La app cumple los requisitos minimos de PWA:

• manifest.json con name, short_name, start_url, display: standalone
• Service Worker registrado con estrategias de cache
• Iconos en formatos 192x192 y 512x512 px (SVG)
• Tema de color y color de fondo definidos

Configuracion del manifest

Moderacion de contenido

usernameModeration.js

Filtra apodos inapropiados del lado del cliente antes de enviarlos al servidor.

Tecnicas de deteccion

• Lista negra — palabras prohibidas directas
• Leet-speak — detecta sustituciones como h4ck3r, @dmin
• Homoglifos — caracteres Unicode visualmente similares (ej: cirilico а vs latino a)
• Normalizacion — convierte a forma canonica para evitar evasiones

Base de datos

MAMB utiliza PostgreSQL como sistema de gestion de base de datos relacional. La conexion se configura mediante la variable de entorno DATABASE_URL.

Modelo de datos

Diagrama de entidades

+---------------------+       +---------------------+
|       obras         |       |      usuarios       |
+---------------------+       +---------------------+
| id (PK, SERIAL)     |       | id (PK, SERIAL)     |
| titulo              |       | apodo (UNIQUE)       |
| descripcion         |       | ciudad               |
| image_url           |       | avatar_index         |
| autor_apodo         |       | password_hash        |
| avatar_index        |       | created_at           |
| likes_count         |       +---------------------+
| rating_total        |
| rating_count        |
| created_at          |
+---------------------+

Relaciones

Actualmente no hay claves foraneas entre tablas. La relacion entre obras y usuarios es implicita a traves del campo autor_apodo.

Tabla obras

Descripcion

Almacena las obras de arte del museo y de los visitantes.

Columnas

Calificacion promedio

Tabla usuarios

Descripcion

Almacena los perfiles de visitantes registrados.

Columnas

Seguridad de contrasenas

Las contrasenas se almacenan como hash bcrypt, nunca en texto plano. El hashing se realiza en el backend antes de insertar en la base de datos.

Conexion

Configuracion del pool

El backend se conecta usando el paquete pg:

const { Pool } = require('pg');
const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  ssl: process.env.NODE_ENV === 'production'
    ? { rejectUnauthorized: false }
    : false
});

Variable de entorno

DATABASE_URL=postgresql://usuario:contraseña@host:5432/mamb

SSL segun entorno

Migracion automatica

Comportamiento

El backend crea las tablas automaticamente al arrancar si no existen. No se usa un sistema de migraciones formal — la creacion es declarativa en el codigo del servidor.

Ventajas

• Sin pasos manuales de migracion
• El esquema siempre esta sincronizado con el codigo
• Despliegue simplificado

Almacenamiento de imagenes

Ubicacion

Las imagenes no se guardan en la base de datos. Se almacenan en el sistema de archivos bajo backend/uploads/. La BD solo guarda la ruta relativa en image_url.

Restricciones

Disco efimero en Render

API REST — Vista general

La API de MAMB gestiona obras de arte, interacciones (likes y calificaciones) y autenticacion. Todos los endpoints retornan y aceptan JSON, excepto la creacion de obras que usa multipart/form-data.

Base URL

URLs por entorno

Resumen de endpoints

Obras (CRUD)

Interacciones

Sistema

Autenticacion

JWT Bearer Token

Los endpoints protegidos requieren un JWT Bearer token en el header:

Authorization: Bearer <token>

Obtencion del token

El token se obtiene al registrarse o iniciar sesion y tiene expiracion automatica.

Endpoints sin autenticacion

Los endpoints de lectura (GET) son publicos y no requieren token.

Health check

Endpoint

GET /api/health

Respuesta exitosa

200 OK:

{
  "status": "ok",
  "museo": "MAMB",
  "db": "PostgreSQL"
}

Uso recomendado

Usar este endpoint para verificar que el servidor y la base de datos estan operativos. Util para monitoreo y para "despertar" el servicio en Render antes de una demo.

Manejo de errores

Formato de error

Todos los errores siguen el mismo formato:

{
  "error": "Descripcion del error"
}

Codigos de estado

Middleware

Cadena de middleware

El backend aplica los siguientes middleware a todas las peticiones, en orden:

Helmet — headers de seguridad

Helmet configura automaticamente headers como:

• X-Content-Type-Options: nosniff
• X-Frame-Options: DENY
• Strict-Transport-Security

CORS — origenes permitidos

CORS esta configurado para permitir peticiones desde el frontend desplegado y desde localhost en desarrollo.

Obras — Referencia completa

Documentacion detallada de todos los endpoints relacionados con obras de arte.

Listar obras

Endpoint

GET /api/obras

Parametros de consulta

Respuesta exitosa

200 OK:

[
  {
    "id": 1,
    "titulo": "Paisaje Costero",
    "descripcion": "Vista del Caribe desde el malecon",
    "image_url": "/uploads/obra_123.jpg",
    "autor_apodo": "Carlos",
    "avatar_index": 0,
    "likes_count": 5,
    "rating_total": 12,
    "rating_count": 3,
    "created_at": "2026-05-29T14:00:00Z"
  }
]

Obtener obra por ID

Endpoint

GET /api/obras/:id

Respuesta exitosa

200 OK: objeto obra (mismo esquema que el listado).

Respuesta de error

404:

{ "error": "Obra no encontrada" }

Crear nueva obra

Endpoint

POST /api/obras
Content-Type: multipart/form-data

Campos del formulario

Restricciones de imagen

Respuesta exitosa

201 Created: objeto obra creado con todos los campos.

Ejemplo con curl

curl -X POST https://www.mamb.online/api/obras \
  -F "image=@mi-obra.jpg" \
  -F "titulo=Mi primera obra" \
  -F "descripcion=Pintura al oleo" \
  -F "autorApodo=Carlos" \
  -F "avatarIndex=3"

Actualizar obra

Endpoint

PATCH /api/obras/:id
Content-Type: application/json

Body de la peticion

{
  "titulo": "Nuevo titulo",
  "descripcion": "Nueva descripcion"
}

Respuesta exitosa

200 OK: obra actualizada con los nuevos valores.

Eliminar obra

Endpoint

DELETE /api/obras/:id

Respuesta exitosa

200 OK:

{ "message": "Obra eliminada" }

Comportamiento

Elimina la obra de la base de datos y el archivo de imagen del disco.

Dar like

Endpoint

POST /api/obras/:id/like

Comportamiento

Incrementa en 1 el contador de likes de la obra.

Respuesta exitosa

200 OK:

{ "likes_count": 6 }

Calificar obra

Endpoint

POST /api/obras/:id/rate
Content-Type: application/json

Body de la peticion

{ "rating": 4 }

Validacion

El valor de rating debe ser un entero entre 1 y 5.

Respuesta exitosa

200 OK:

{
  "rating_total": 16,
  "rating_count": 4
}

Calcular promedio

Esquema completo de una obra

Objeto obra

{
  "id": 1,
  "titulo": "Paisaje Costero",
  "descripcion": "Vista del Caribe desde el malecon",
  "image_url": "/uploads/obra_1717000000000.jpg",
  "autor_apodo": "Carlos",
  "avatar_index": 2,
  "likes_count": 12,
  "rating_total": 35,
  "rating_count": 8,
  "created_at": "2026-05-29T14:00:00.000Z"
}

Descripcion de campos