Sistema de almacén doméstico en un solo binario de 10 MB: Go sin bases de datos, React 19 e impresión de etiquetas desde el navegadorArtículo · digest del 22 de noviembre
Bodegón de un taller doméstico con el terminal autónomo HomeStorage, cajas con códigos QR, cinta métrica y una mini impresora de etiquetas
Artículo4 secciones≈ 10 min

Sistema de almacén doméstico en un solo binario de 10 MB: Go sin bases de datos, React 19 e impresión de etiquetas desde el navegador

Un solo archivo ejecutable de unos 10 MB, arranque por debajo de 20 milisegundos y menos de 25 MB de memoria RAM: así funciona el sistema doméstico de almacenamiento por ubicaciones HomeStorage bajo licencia Apache-2.0. Su creador, Evgeny (@GraviJohn), eliminó de la arquitectura todo lo que suele arrastrarse por costumbre a los proyectos personales: PostgreSQL, SQLite, Redis, Nginx y Docker. Toda la base vive en un único archivo JSON legible y la interfaz en React 19 queda empaquetada dentro del propio binario.

Por qué un garaje necesita su propio WMS y por qué la nube estorba

Es una escena familiar: en el garaje y el trastero se acumulan durante años sobrantes de obra, repuestos del coche, materiales de pasatiempos y equipo como esquís. Llega un punto en que sale más fácil comprar una pieza nueva que revolver diez cajas buscando la vieja.

En los almacenes reales esto se resuelve con un WMS, sistemas de gestión por ubicaciones donde cada estantería, balda y contenedor tiene un código corto. Pero las soluciones corporativas son demasiado pesadas para una familia: exigen servidores, roles e internet estable. Los servicios en la nube también cansan pronto: en el sótano o el garaje el Wi-Fi apenas llega, y a casi nadie le apetece pagar una suscripción mensual por listar sus propios tornillos.

De ahí nacieron requisitos claros para una herramienta casera. Modo Offline-First en la red local, para que vuele tanto en la computadora de casa como en un teléfono viejo en el sótano. Cero usuarios ni contraseñas dentro de la familia, para que todos en casa la usen de verdad. Toma rápida de fotos directo desde el formulario de alta sin llenar la galería personal del móvil. Y respaldos simples copiando un solo archivo de datos junto con la carpeta de fotos.

Backend en un solo archivo: db.json, sync.RWMutex y //go:embed

El servidor se escribió en Go puro (net/http) sin ninguna dependencia externa. Toda la estructura de ubicaciones, categorías y fichas de objetos vive en memoria dentro de DatabaseSnapshot y se serializa en un único archivo legible db.json.

Para evitar que peticiones desde distintas pestañas choquen o dejen el archivo escrito a medias, el acceso concurrente y la reescritura atómica se protegen con el estándar sync.RWMutex. Es un bloqueo de lectura-escritura: RLock deja pasar a muchos lectores en paralelo, mientras Lock entrega el archivo en exclusiva a un solo escritor durante una fracción de milisegundo hasta volcar la instantánea completa al disco.

El frontend compilado (dist/) se incrusta directamente dentro del programa con la directiva //go:embed, un comentario especial con el que el compilador de Go empaqueta los archivos estáticos en el binario final.

// Incrustamos el frontend React compilado dentro del binario Go
//go:embed all:dist
var staticFiles embed.FS

// Store protege la instantánea db.json contra carreras de escritura
type Store struct {
    mu   sync.RWMutex
    data DatabaseSnapshot
}

El resultado es un único archivo para Windows, Linux, macOS o Raspberry Pi, fácil de registrar como servicio mediante systemd o NSSM. El proyecto se compila con cuatro comandos.

# Compilamos los estáticos del frontend con Vite
npm install
npm run build

# Compilamos el backend Go sin símbolos de depuración
cd go-backend
go build -ldflags="-s -w" -o inventory.exe main.go

Las banderas -s -w eliminan la tabla de símbolos y la información de depuración, comprimiendo inventory.exe a unos 10 MB. Al arrancar, el servidor sirve la interfaz de inmediato, atiende peticiones de la API y consume menos de 25 MB de memoria.

Las fotos no se codifican en base64 ni requieren almacenamiento de objetos. Se guardan en disco dentro de subcarpetas que replican el código y nombre del lugar, por ejemplo uploads/h-c1-s3-b1_Box_1/. El nombre de cada archivo empieza siempre con el prefijo [item_id]_[timestamp]_[rand].jpg. Este esquema simple ahorra muchísimo código: al borrar o mover un objeto, el servidor revisa el prefijo en tiempo constante O(1), no toca las fotos ajenas de la misma caja, traslada los archivos necesarios a la carpeta nueva y elimina la anterior si queda vacía.

Frontend para el garaje: matrioska, cámara y mal Wi-Fi

El cliente se armó con React 19, TypeScript, Tailwind CSS v4 y Vite. Toda la lógica sigue una jerarquía estricta de cuatro niveles tipo matrioska: Ubicación (Casa) -> Mueble (Armario) -> Balda (numerada de abajo hacia arriba) -> Contenedor (Caja).

Las baldas y cajas se pueden arrastrar entre armarios mediante Drag-and-Drop. Ante cualquier movimiento, cliente y servidor recalculan de forma sincronizada códigos cortos como h-c1-s3-b1 y bloquean dependencias cíclicas.

Contra borrados accidentales por las prisas protege Safe Deletion: el sistema no permite eliminar una balda o caja si dentro de ella o en contenedores hijos figura al menos un objeto. En lugar de perder datos, muestra la lista de artículos y propone moverlos. Haz clic en el prototipo interactivo de abajo para ver cómo cambian el código de ubicación, la ruta del archivo y la respuesta al borrar.

Prototipo interactivo: código de ubicación, ruta de foto y Safe Deletion

El mismo código de ubicación aparece en la etiqueta de papel, en el árbol de la interfaz y en el nombre de la carpeta en disco. Incluso si el programa deja de abrirse dentro de cinco años, basta con abrir uploads/ en el explorador de archivos y todo seguirá siendo comprensible.

Los cortes de Wi-Fi en el sótano se resuelven con idempotencia, la propiedad por la cual reenviar un formulario con el mismo ID único actualiza el registro en lugar de crear duplicados. La deduplicación opera en ambos extremos: en inventoryStorage.ts del cliente y en storage.go del servidor.

Para tomar fotos de piezas desde el teléfono bastó un solo atributo HTML, capture con valor environment.

<!-- Abre directo la cámara trasera del teléfono (user abriría la frontal) -->
<input type="file" accept="image/*" capture="environment" />

El navegador móvil se salta la galería y enciende al instante la cámara principal. Y si fotografiaste unos tornillos, te arrepentiste y cerraste el formulario sin guardar, el cliente envía enseguida DELETE /api/upload para que no se acumulen archivos huérfanos en el disco.

Impresión de etiquetas, respaldo offline y límites del minimalismo

La generación de etiquetas se movió por completo al navegador: la librería qrcode dibuja códigos QR sobre HTML5 Canvas, mientras un generador SVG propio arma códigos de barras Code-128 listos para impresoras térmicas de rollo y hojas A4.

El estado del cliente vive encapsulado en InventoryStorageManager. La búsqueda funciona en tiempo real por subcadena sobre nombre, SKU, código de barras, dimensiones, notas, categoría y código de ubicación. Al abrir la página, el cliente intenta sincronizarse con el servidor mediante syncWithServer y, si el backend no responde (por ejemplo, al abrir una demo estática), pasa de forma transparente a localStorage. Además sumaron soporte multiidioma para 11 lenguas, incluido RTL (escritura de derecha a izquierda para árabe), con LanguageContext y un diccionario JSON sencillo.

Este minimalismo se paga con dos límites claros. El primero es la escala: db.json bajo sync.RWMutex mueve con soltura de 1 a 5 usuarios y miles de fichas, pero con decenas de miles de objetos y escrituras concurrentes frecuentes, reescribir el archivo entero se volverá un cuello de botella. En ese punto, sin perder el formato de «un solo binario», conviene pasar a SQLite (en Go puro con modernc.org/sqlite), y para decenas de empleados y roles ya toca levantar PostgreSQL.

El segundo límite es la seguridad. Prescindir de contraseñas solo es cómodo dentro de una red doméstica de confianza. No debes exponer HomeStorage directamente a internet abierto: para acceso remoto hace falta poner delante del binario un reverse-proxy con autenticación o entrar por VPN.

Quiero un análisis detalladoLos votos ayudan a elegir qué analizar a fondo. Este material tiene 0 votos.
Fuentes · 5