MallHub

Plataforma multi-tenant para centros comerciales que conecta a clientes, tiendas y administradores en una sola experiencia digital. Incluye una aplicación web SSR y una aplicación móvil nativa construidas sobre un monorepo compartido.

Tabla de contenidos

Descripción general
Stack tecnológico
Arquitectura
Estructura del monorepo
Requisitos previos
Primeros pasos
Variables de entorno
Scripts disponibles
Aplicación Web
Aplicación Móvil
Paquetes compartidos
Base de datos
Infraestructura Docker
Roles y permisos
Convenciones de commits

Descripción general

MallHub es un marketplace para centros comerciales que permite:

A los clientes explorar malls, tiendas y productos, gestionar reservaciones y guardar favoritos.
A los administradores de tienda (Admin Local) gestionar su catálogo de productos, reservaciones y promociones desde web y móvil.
A los administradores de centro comercial (Admin CC) supervisar tiendas, eventos, métricas y reportes IA de su mall.
A los administradores de plataforma (Admin Platform) gestionar malls, usuarios, facturación, moderación, campañas y salud del sistema.

Stack tecnológico

Web (`apps/web`)

Categoría	Tecnología
Framework	React Router v7 (SSR)
Base de datos	PostgreSQL 17 + Prisma 7
API	tRPC 11 + TanStack Query 5
Autenticación	Better Auth 1.5 (plugins: `admin`, `organization`)
Autorización	CASL
Formularios	TanStack Form 1 + Zod 4
UI	shadcn/ui + Tailwind CSS v4
Iconos	Hugeicons
i18n	Paraglide JS 2 (ES / EN)
Almacenamiento de archivos	MinIO (compatible S3)
Notificaciones	BullMQ + Redis + Resend
IA	OpenAI GPT-4o-mini

Móvil (`apps/mobile`)

Categoría	Tecnología
Framework	Expo 54 + React Native 0.81
Routing	Expo Router 6
Datos	TanStack Query 5
Almacenamiento seguro	Expo SecureStore
Media	Expo Image Picker + Expo Camera
Iconos	Hugeicons React Native
QR	react-native-qrcode-svg

Tooling

Herramienta	Uso
pnpm 10	Gestor de paquetes
Turborepo 2	Orquestación de tareas del monorepo
Biome 2	Linting y formateo
Husky + CommitLint	Git hooks y convención de commits
Docker Compose	Infraestructura local

Arquitectura

Browser / Mobile
      │
      ▼
React Router v7 SSR (apps/web)
      │
      ├── /api/trpc/*     →  tRPC Router  →  Prisma  →  PostgreSQL
      ├── /api/auth/*     →  Better Auth Handler
      └── /:locale?/*     →  UI Routes (SSR)

                                 │
                          BullMQ Queue
                                 │
                            Redis 7
                                 │
                           Resend (email)

                          MinIO / S3
                      (imágenes y archivos)

Todo el código del servidor vive bajo apps/web/app/features/.server/.
Los procedimientos tRPC se organizan por feature en archivos *.query.ts / *.mutation.ts y se registran en trpc.router.ts.
Better Auth expone la sesión al contexto de tRPC; CASL construye las habilidades a partir del rol del usuario.
Las notificaciones por email se encolan de forma asíncrona y nunca bloquean flujos de autenticación o mutaciones.
La app móvil se comunica con el backend web a través del cliente HTTP de tRPC en apps/mobile/lib/api.ts.

Estructura del monorepo

MallHub/
├── apps/
│   ├── web/                     # Aplicación React Router v7 (SSR)
│   │   ├── app/
│   │   │   ├── features/        # Módulos por dominio
│   │   │   │   ├── .server/     # Código exclusivo del servidor (Prisma, tRPC, Auth)
│   │   │   │   ├── home/
│   │   │   │   ├── browse/
│   │   │   │   ├── search/
│   │   │   │   ├── malls/
│   │   │   │   ├── stores/
│   │   │   │   ├── reservations/
│   │   │   │   ├── customer/
│   │   │   │   ├── store-admin-local/
│   │   │   │   ├── admin-cc/
│   │   │   │   └── admin-platform/
│   │   │   ├── routes.ts        # Definición de rutas
│   │   │   └── root.tsx         # Layout raíz + middleware i18n
│   │   ├── prisma/
│   │   │   └── schema.prisma    # Schema de base de datos
│   │   ├── messages/
│   │   │   ├── es.json          # Traducciones español (base)
│   │   │   └── en.json          # Traducciones inglés
│   │   └── public/
│   │
│   └── mobile/                  # Aplicación Expo + React Native
│       ├── app/
│       │   ├── (tabs)/          # Navegación principal (cliente)
│       │   ├── (admin-local)/   # Panel del administrador de tienda
│       │   ├── auth/            # Login y registro
│       │   ├── mall/[mallId]/   # Detalle de mall
│       │   ├── store/[storeId]/ # Detalle de tienda
│       │   ├── product/[id]/    # Detalle de producto
│       │   ├── reserve/[id]/    # Flujo de reserva
│       │   ├── reservation/[id]/ # Detalle de reservación
│       │   └── onboarding.tsx
│       └── lib/
│           └── api.ts           # Cliente tRPC para móvil
│
├── packages/
│   ├── ui/                      # @mallhub/ui — componentes compartidos (shadcn)
│   └── notifications/           # @mallhub/notifications — cola BullMQ + Redis
│
├── docs/                        # Guías técnicas del proyecto
├── docker-compose.dev.yml       # Infraestructura para desarrollo
├── docker-compose.local-prod.yml # Infraestructura para producción local
├── turbo.json
└── pnpm-workspace.yaml

Requisitos previos

Herramienta	Versión mínima
Node.js	20 LTS
pnpm	10
Docker + Docker Compose	Cualquier versión reciente
Expo CLI (solo mobile)	Incluido en dev deps

Primeros pasos

1. Clonar el repositorio

git clone <url-del-repositorio>
cd MallHub

2. Instalar dependencias

pnpm install

3. Configurar variables de entorno

cp apps/web/.env.example apps/web/.env

Edita apps/web/.env con tus valores. Consulta la sección Variables de entorno para una descripción completa.

4. Levantar la infraestructura

# Entorno de desarrollo (PostgreSQL, Redis, MinIO, Mailpit)
docker compose -f docker-compose.dev.yml up -d

5. Ejecutar migraciones y seed

# Aplica las migraciones de Prisma
pnpm --filter @mallhub/web run prisma:migrate

# Puebla la base de datos con datos iniciales
pnpm --filter @mallhub/web run prisma:seed

6. Compilar traducciones

pnpm --filter @mallhub/web run i18n:compile

7. Iniciar el servidor de desarrollo

# Todos los workspaces en paralelo
pnpm dev

# Solo la aplicación web
pnpm --filter @mallhub/web run dev

# Solo la aplicación móvil
pnpm --filter @mallhub/mobile run dev

La aplicación web estará disponible en http://localhost:5173.
El servidor de email de desarrollo (Mailpit) en http://localhost:8025.
La consola de MinIO en http://localhost:9001.

Variables de entorno

Todas las variables se definen en apps/web/.env. El archivo apps/web/.env.example sirve de referencia.

Base de datos

Variable	Descripción	Ejemplo
`DATABASE_URL`	URL de conexión a PostgreSQL	`postgresql://postgres:postgres@localhost:5432/mallhub`

Autenticación

Variable	Descripción
`BETTER_AUTH_URL`	URL base de la aplicación (sin slash final)
`BETTER_AUTH_SECRET`	Secreto para firmar sesiones (mínimo 32 caracteres)

Credenciales del admin inicial

Variable	Descripción
`ADMIN_EMAIL`	Email del administrador de plataforma creado en el seed
`ADMIN_NAME`	Nombre del administrador
`ADMIN_PASSWORD`	Contraseña del administrador

Email (Resend)

Variable	Descripción
`RESEND_API_KEY`	API key de Resend
`RESEND_FROM_EMAIL`	Dirección remitente
`RESEND_FROM_NAME`	Nombre remitente

Cola de notificaciones (Redis + BullMQ)

Variable	Default	Descripción
`REDIS_URL`	—	URL de conexión a Redis
`NOTIFICATIONS_WORKER_CONCURRENCY`	`5`	Trabajos paralelos del worker
`NOTIFICATIONS_WORKER_LIMIT_MAX`	`60`	Máximo de emails por ventana
`NOTIFICATIONS_WORKER_LIMIT_DURATION_MS`	`60000`	Ventana de rate limit en ms

Almacenamiento de archivos (MinIO / S3)

Variable	Default	Descripción
`MINIO_ENDPOINT`	`http://localhost:9000`	Endpoint interno de MinIO
`MINIO_ACCESS_KEY`	`minioadmin`	Access key
`MINIO_SECRET_KEY`	`minioadmin`	Secret key
`MINIO_BUCKET`	`mallhub`	Nombre del bucket
`MINIO_PUBLIC_URL`	`http://localhost:9000`	URL pública para las URLs de imágenes

Inteligencia Artificial

Variable	Descripción
`OPENAI_API_KEY`	API key de OpenAI (para reportes IA del Admin CC)

Frontend

Variable	Default	Descripción
`VITE_APP_API_URL`	`http://mallhub.lat`	URL de la API consumida desde el cliente

Scripts disponibles

Ejecutar desde la raíz del monorepo:

Comando	Descripción
`pnpm dev`	Inicia todos los workspaces en modo desarrollo
`pnpm build`	Construye todos los workspaces
`pnpm lint`	Ejecuta Biome en todos los workspaces
`pnpm format`	Formatea todos los archivos con Biome
`pnpm type-check`	Verifica tipos TypeScript en todos los workspaces
`pnpm --filter @mallhub/web run prisma:migrate`	Aplica migraciones de Prisma
`pnpm --filter @mallhub/web run prisma:seed`	Ejecuta el seed de la base de datos
`pnpm --filter @mallhub/web run i18n:compile`	Compila los mensajes de Paraglide

Validación obligatoria antes de cada commit: pnpm format → pnpm lint → pnpm type-check

Aplicación Web

Rutas principales

Públicas

Ruta	Descripción
`/`	Landing page con malls y productos destacados
`/malls`	Listado de centros comerciales
`/malls/:mallId`	Detalle de un mall
`/malls/:mallId/stores`	Tiendas de un mall
`/stores/:storeId`	Detalle de una tienda
`/products/:productId`	Detalle de un producto
`/search`	Búsqueda global

Autenticación

Ruta	Descripción
`/auth/login`	Inicio de sesión
`/auth/register`	Registro de cuenta
`/auth/reset-password`	Solicitud de recuperación de contraseña

Dashboard del cliente

Ruta	Descripción
`/dashboard`	Resumen de la cuenta
`/dashboard/reservations/:id`	Detalle de una reservación
`/products/:productId/reserve`	Flujo de reserva (3 pasos)

Admin Local (tienda)

Ruta	Descripción
`/store-local/dashboard`	Panel principal
`/store-local/products`	Gestión de productos
`/store-local/reservations`	Gestión de reservaciones
`/store-local/promotions`	Gestión de promociones
`/store-local/config`	Configuración de la tienda

Admin CC (centro comercial)

Ruta	Descripción
`/admin-cc/dashboard`	Métricas del mall
`/admin-cc/stores`	Gestión de tiendas
`/admin-cc/events`	Eventos del mall
`/admin-cc/ai-reports`	Reportes generados con IA
`/admin-cc/config`	Configuración del mall

Admin Platform

Ruta	Descripción
`/admin/dashboard`	Métricas globales
`/admin/malls`	Gestión de centros comerciales
`/admin/stores`	Gestión de tiendas
`/admin/users`	Gestión de usuarios y roles
`/admin/billing`	Suscripciones y pagos
`/admin/campaigns`	Campañas de marketing
`/admin/moderation`	Reportes de moderación
`/admin/audit`	Registro de auditoría
`/admin/health`	Estado de salud del sistema

Aplicación Móvil

Pantallas

Tabs (cliente autenticado)

Tab	Descripción
Home	Feed con malls y productos destacados
Search	Búsqueda con historial
Favorites	Tiendas y productos guardados
Reservations	Lista de reservaciones del usuario
Profile	Perfil y configuración

Pantallas de detalle

Pantalla	Descripción
`mall/[mallId]`	Información y galería del mall
`mall/[mallId]/stores`	Tiendas del mall
`store/[storeId]`	Perfil de la tienda
`product/[productId]`	Detalle de producto con stock
`reserve/[productId]`	Flujo de reserva con selector de fecha
`reservation/[reservationId]`	Detalle con código QR

Admin Local (móvil)

Pantalla	Descripción
Dashboard	Estadísticas rápidas
Products	Listado con edición y eliminación
Add / Edit Product	Formulario con carga de imagen
Reservations	Reservaciones recibidas
Scan QR	Escáner para confirmar reservaciones
Promotions	Gestión de promociones
Config	Configuración de la tienda

Paquetes compartidos

`@mallhub/ui`

Librería de componentes basada en shadcn/ui y Tailwind CSS v4. Todos los tokens de color y tipografía están definidos como variables CSS en packages/ui/src/global.css. Los componentes se consumen directamente desde @mallhub/ui en la aplicación web.

`@mallhub/notifications`

Infraestructura de cola de emails basada en BullMQ y Redis. Expone un dispatcher que encola trabajos de envío sin bloquear el hilo principal. La entrega final se realiza a través de Resend.

Base de datos

El schema completo se encuentra en apps/web/prisma/schema.prisma. A continuación, los modelos agrupados por dominio:

Dominio	Modelos
Usuarios y auth	`User`, `Session`, `Account`, `Verification`, `UserProfile`
Organizaciones	`Organization`, `Member`, `Invitation`
Malls	`Mall`, `MallGalleryImage`, `MallEvent`
Tiendas	`Store`, `StoreRegistrationRequest`
Productos	`Product`, `Promotion`
Reservaciones	`Reservation`
Favoritos	`FavoriteStore`, `FavoriteProduct`, `FavoritePromotion`
Analytics	`SearchLog`, `DailyMallMetric`, `DailyPlatformMetric`, `AiRun`
Administración	`AdminCcAssignment`, `ModerationReport`, `AuditEvent`
Facturación	`BillingSubscription`, `BillingPayment`, `BillingCollectionAlert`
Campañas	`Campaign`, `CampaignTargetMall`, `CampaignDailyMetric`
Salud	`PlatformServiceSnapshot`, `PlatformHealthIncident`

Infraestructura Docker

El proyecto incluye dos configuraciones de Docker Compose:

Desarrollo (`docker-compose.dev.yml`)

Almacenamiento en memoria, ideal para desarrollo local rápido.

docker compose -f docker-compose.dev.yml up -d

Servicio	Puerto	Descripción
PostgreSQL 17	5432	Base de datos principal
Redis 7	6379	Cola de notificaciones
MinIO	9000 / 9001	Almacenamiento de archivos / Consola web
Mailpit	1025 / 8025	Servidor SMTP local / Bandeja de pruebas

Producción local (`docker-compose.local-prod.yml`)

Con volúmenes persistentes e imagen Docker de la aplicación.

docker compose -f docker-compose.local-prod.yml up -d

Incluye un servicio minio-init que crea el bucket automáticamente al iniciar, y el servicio app que corre la build de Node.js en el puerto configurado por APP_HOST_PORT (por defecto 80).

Roles y permisos

El sistema de autorización combina Better Auth (gestión de sesiones y roles) con CASL (habilidades por recurso).

Rol	Descripción
`CUSTOMER`	Usuario final. Puede explorar, reservar y gestionar su perfil.
`ADMIN_LOCAL`	Administrador de una tienda. Gestiona productos, reservaciones y promociones de su tienda.
`ADMIN_CC`	Administrador de un centro comercial. Supervisa tiendas, eventos, métricas y reportes IA.
`ADMIN_PLATFORM`	Superadministrador. Acceso completo a todos los recursos del sistema.

Las constantes de roles se definen en better-auth-access-control.lib.ts. Los tres archivos que deben mantenerse alineados son:

better-auth-server.lib.ts
app-ability.lib.ts
trpc.init.ts

Convenciones de commits

Este proyecto usa Conventional Commits validado con CommitLint y Husky.

<type>(<scope>): <descripción>

Tipos válidos: feat, fix, refactor, docs, style, test, chore, perf, ci

Ejemplos:

feat(reservations): add cancellation flow with CASL guard
fix(mobile): handle expired session token on startup
refactor(admin-cc): extract store toggle into isolated mutation
docs: update environment variables reference

Documentación adicional

Los archivos en docs/ amplían aspectos específicos del proyecto:

Archivo	Contenido
`trpc.md`	Estructura de tRPC y localización de errores del servidor
`forms.md`	Guía detallada de TanStack Form con Zod codecs
`style.md`	Convenciones de diseño y código
`roles-permissions-organizations-guide.md`	Arquitectura de auth y autorización
`paraglide-i18n-quick-guide.md`	Configuración de i18n con Paraglide
`bitacora-prompts.md`	Registro de prompts de implementación usados durante el desarrollo

Name		Name	Last commit message	Last commit date
Latest commit History 106 Commits
.github		.github
.husky		.husky
apps		apps
docs		docs
load-tests		load-tests
messages		messages
packages		packages
project.inlang		project.inlang
.dockerignore		.dockerignore
.gitattributes		.gitattributes
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
README.md		README.md
biome.json		biome.json
commitlint.config.cjs		commitlint.config.cjs
database.dbml		database.dbml
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.local-prod.yml		docker-compose.local-prod.yml
docker-entrypoint.sh		docker-entrypoint.sh
eas.json		eas.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
skills-lock.json		skills-lock.json
turbo.json		turbo.json

Folders and files

Latest commit

History

Repository files navigation

MallHub

Tabla de contenidos

Descripción general

Stack tecnológico

Web (apps/web)

Móvil (apps/mobile)

Tooling

Arquitectura

Estructura del monorepo

Requisitos previos

Primeros pasos

1. Clonar el repositorio

2. Instalar dependencias

3. Configurar variables de entorno

4. Levantar la infraestructura

5. Ejecutar migraciones y seed

6. Compilar traducciones

7. Iniciar el servidor de desarrollo

Variables de entorno

Base de datos

Autenticación

Credenciales del admin inicial

Email (Resend)

Cola de notificaciones (Redis + BullMQ)

Almacenamiento de archivos (MinIO / S3)

Inteligencia Artificial

Frontend

Scripts disponibles

Aplicación Web

Rutas principales

Públicas

Autenticación

Dashboard del cliente

Admin Local (tienda)

Admin CC (centro comercial)

Admin Platform

Aplicación Móvil

Pantallas

Tabs (cliente autenticado)

Pantallas de detalle

Admin Local (móvil)

Paquetes compartidos

@mallhub/ui

@mallhub/notifications

Base de datos

Infraestructura Docker

Desarrollo (docker-compose.dev.yml)

Producción local (docker-compose.local-prod.yml)

Roles y permisos

Convenciones de commits

Documentación adicional

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Web (`apps/web`)

Móvil (`apps/mobile`)

`@mallhub/ui`

`@mallhub/notifications`

Desarrollo (`docker-compose.dev.yml`)

Producción local (`docker-compose.local-prod.yml`)

Packages