Nexum
Tu hogar, más simple.
Una sola app para todos los dispositivos de casa.
Qué es esto
Nexum es una app de gestión del hogar que funciona como paraguas de módulos.
Cada módulo controla una categoría de aparatos, tiene su propia cara y su propia
lógica, pero todos comparten cuenta, casas, habitaciones, permisos,
notificaciones y automatizaciones.
| Módulo | Categoría | Estado |
|---|
| Coolio | Climatización (splits de A/A por infrarrojos) | En construcción |
| Plantico | Riego de plantas de interior | Fase 2 — estructura preparada, sin implementar |
| Iluminación, Seguridad, Energía | — | Futuro |
El hardware es propio: placas ESP32, una por aparato controlado.
Esta guía asume que no sabes programar
Y eso está bien. Se explica qué instalar, en qué orden, qué deberías ver en
pantalla si todo fue bien y qué señal indica que algo falló.
Si en algún punto la pantalla no se parece a lo descrito, para ahí. Seguir
adelante con un paso a medias es lo que convierte un problema pequeño en una
tarde perdida.
Antes de empezar: cinco palabras
| Palabra | Qué significa |
|---|
| Terminal | La ventana negra donde se escriben órdenes. En Mac se llama Terminal; en Windows, PowerShell |
| Repositorio | Esta carpeta de archivos, con su historial de cambios |
| Dependencias | Código de otros que este proyecto necesita. Se descargan solas |
| Variable de entorno | Un dato de configuración (una clave, una dirección) que no se escribe dentro del código porque es secreto |
| Backend | La parte que vive en Internet: la base de datos y la lógica. Aquí, Supabase |
Puesta en marcha
Paso 1 — Instalar Node.js
Node.js es el motor que ejecuta todo esto.
- Ve a https://nodejs.org y descarga la versión LTS (la de la izquierda).
- Instálala dándole a "Siguiente" a todo.
- Abre la terminal y escribe:
node --version
Bien: sale algo como v22.11.0. Cualquier número 20 o superior vale.
Mal: sale command not found. La instalación no terminó o hay que cerrar y
volver a abrir la terminal.
Paso 2 — Descargar el proyecto e instalar sus dependencias
git clone https://github.com/fmarquezarate-png/nexum.git
cd nexum
npm install
Tarda entre uno y tres minutos y escupe muchísimo texto. Es normal.
Bien: al final aparece algo como added 1043 packages in 1m.
Mal: aparecen líneas que empiezan por npm ERR!. Lee la primera; casi
siempre es que Node es demasiado antiguo.
Los avisos que empiezan por npm WARN no son errores. Se ignoran.
Paso 3 — Crear el proyecto en Supabase
Supabase es la base de datos en Internet. Plan gratuito de sobra para esto.
- Entra en https://supabase.com y crea una cuenta.
- New project. Ponle de nombre
nexum.
- Región: West EU (Ireland) o Central EU (Frankfurt), las más cercanas.
- Te pide una contraseña para la base de datos. Guárdala en un sitio seguro:
no se puede recuperar.
- Espera unos dos minutos mientras se crea.
Paso 4 — Copiar las dos claves
En Supabase: tu proyecto → Project Settings → API. Hay dos datos que
necesitas:
| Dato | Aspecto |
|---|
| Project URL | https://abcdefghij.supabase.co |
| anon public | Un texto larguísimo que empieza por eyJ... |
Verás también una clave llamada service_role. Esa no se toca ahora.
Salta todas las protecciones de seguridad y solo puede vivir en un servidor,
nunca dentro de la app del móvil. Más abajo se explica cuándo se usa.
Ahora, en la terminal, dentro de la carpeta nexum:
cp apps/mobile/.env.example apps/mobile/.env
Eso crea el archivo apps/mobile/.env. Ábrelo con cualquier editor de texto y
pega tus dos datos entre las comillas:
EXPO_PUBLIC_SUPABASE_URL="https://abcdefghij.supabase.co"
EXPO_PUBLIC_SUPABASE_ANON_KEY="eyJhbGciOi..."
Guarda y cierra.
Este archivo nunca se sube a GitHub. Ya está bloqueado para que no pueda
subirse por accidente.
Paso 5 — Crear las tablas en la base de datos
npx supabase login
Se abre el navegador y das permiso. Luego:
npx supabase link --project-ref TU_REF
npx supabase db push
TU_REF es el código que aparece en la dirección de tu proyecto en Supabase:
https://supabase.com/dashboard/project/ → abcdefghij
Bien: lista las migraciones aplicadas, sin rojo. Comprueba en Supabase →
Table Editor que aparecen homes, devices, coolio_state, commands…
Mal: cualquier línea roja. La más común es relation already exists: las
tablas ya estaban creadas.
Paso 6 — Arrancar la app
npm run app
Aparece un código QR en la terminal.
En tu móvil: instala la app Expo Go (App Store o Google Play) y escanea
el QR. En iPhone se escanea con la cámara normal; en Android, desde dentro de
Expo Go.
Bien: en el móvil se abre Nexum con las cinco pestañas abajo — Inicio,
Dispositivos, Automatizaciones, Estadísticas, Ajustes — y tarjetas grises que
dicen qué falta por hacer en cada fase. Eso es exactamente lo que debe verse
ahora mismo: la estructura está montada, la lógica llega en las fases
siguientes.
Mal:
| Lo que ves | Qué pasa |
|---|
| Pantalla roja: "Faltan las claves de Supabase" | El paso 4 quedó a medias. Revisa el .env y reinicia el servidor |
| El móvil no encuentra el servidor | Móvil y ordenador tienen que estar en el mismo WiFi |
| Errores de versiones al arrancar | Ejecuta npm run fix-versions --workspace apps/mobile |
Para parar el servidor: Ctrl + C en la terminal.
Qué hay en cada carpeta
nexum/
├── apps/mobile/ La app del móvil (iOS y Android, mismo código)
│ ├── app/ Las pantallas y su navegación
│ ├── core/ Lo COMÚN: cuentas, casas, permisos, dispositivos
│ ├── modules/ Lo PROPIO de cada módulo: coolio/, plantico/
│ ├── ui/ Colores, espaciados y piezas visuales compartidas
│ └── lib/ Conexión con Supabase, utilidades, textos
│
├── services/mqtt-bridge/ Servicio encendido 24/7 que escucha a los aparatos
│
├── supabase/ La base de datos
│ ├── migrations/ El esquema, en archivos SQL numerados
│ └── functions/ Los trocitos de backend
│
├── packages/
│ ├── contracts/ ⭐ FUENTE DE VERDAD del contrato con los aparatos
│ └── shared-types/ Tipos compartidos entre app y backend
│
├── firmware/ Contrato para el agente de firmware (aquí no se programa)
│
└── docs/ La documentación de verdad
Lo más importante de entender
core/ es el centro comercial. modules/ son las tiendas.
Todo lo que necesitarían también Plantico, Iluminación o Seguridad —cuentas,
casas, habitaciones, permisos, notificaciones— vive en core/. Lo que solo le
importa a un módulo, vive en su carpeta.
La prueba de que esto está bien hecho: añadir Plantico debe consistir en
añadir carpetas y tablas, nunca en refactorizar el núcleo.
Documentación
Léelos en este orden:
Estado del proyecto
| Fase | Qué incluye | Estado |
|---|
| 0 · Esqueleto | Monorepo, esquema con RLS, contratos, app navegando | ✅ Hecho |
| 1 · Núcleo | Registro, login, casas, habitaciones, miembros, códigos QR | ✅ Hecho |
| 2 · Coolio | Emparejado real, comandos con auditoría, telemetría en vivo | ⬜ Siguiente |
| 3 · Automatizaciones | Horarios, umbrales, notificaciones, estadísticas | ⬜ |
| 4 · Plantico | Riego. La prueba de que el núcleo está bien hecho | ⬜ |
Lo que funciona ahora: crear cuenta, iniciar sesión, recuperar contraseña,
el asistente de alta de casa, gestionar casas, habitaciones y miembros, y
generar y canjear códigos de invitado con su QR.
Lo que todavía no: los dispositivos. La pestaña de Dispositivos enseña el
selector de casa y un hueco, porque hasta la fase 2 no se puede emparejar nada.
Las pantallas de Automatizaciones y Estadísticas están maquetadas con tarjetas
que indican qué falta y en qué fase llega. El servicio mqtt-bridge y las Edge
Functions son esqueletos a propósito.
Dos reglas que no se rompen
1. Ningún secreto entra en el repositorio. Ni claves, ni contraseñas, ni
tokens. Los archivos .env.example listan qué hace falta, con el valor vacío y
la explicación de dónde sale cada cosa.
2. El contrato manda sobre el código. Si un topic MQTT o un campo de un
mensaje no está en packages/contracts/, no existe. Cualquier cambio se hace
ahí primero y luego se propaga a la app, al backend y al firmware.
