Portafolio / ERP de trazabilidad y costos
Del café verde al pedido, con costo real.
Broo Café compra café verde a una finca, lo envía a una tostadora aliada, empaca grano, drip y cold brew, y vende sobre todo por WooCommerce, además de WhatsApp. Diseñamos y construimos un ERP que sigue cada lote desde la finca hasta el pedido despachado y convierte ese recorrido en costo real, margen por pedido y relación con el cliente.
01El reto
Una cadena de café completa en una marca pequeña.
Broo no compra café listo para vender. Compra verde a una finca de Antioquia, lo manda a tostar afuera, pierde peso en la tostión, compra natural ya tostado, y empaca en varios tamaños de bolsa, kits de drip de 15 sobres y cold brew de 700 ml. Cada paso cambia el costo del café que termina en una bolsa, y ese costo vivía repartido entre facturas, hojas de cálculo y la memoria del equipo.
Las preguntas del negocio eran concretas: cuánto costó producir cada lote, cuánto inventario queda, cuánto deja cada pedido después del café, el empaque, la comisión de la pasarela y el subsidio de envío, y qué presupuesto de adquisición es sostenible. Todo sin confundir facturación con utilidad, y con WooCommerce como canal principal.
Lo que había que coordinar
- 01Café verde con finca, variedad, proceso y origen
- 02Tostión tercerizada y su merma
- 03Recetas y órdenes de producción
- 04Empaques por unidad vendida
- 05Pedidos de WooCommerce, WhatsApp y ferias
- 06Despacho, guía y etiqueta
- 07Clientes y consentimiento (Ley 1581)
- 08Correos del pedido y campañas
- 09Gastos, pauta y rentabilidad
Nuestro rol
Modelado del dominio y del producto, arquitectura, sistema visual e interfaz, desarrollo frontend y backend, integraciones (WooCommerce, Resend, Gemini, almacenamiento privado y n8n), pruebas automatizadas, guías de uso dentro del panel y despliegue.
02La regla
La decisión que ordenó todo el sistema.
El inventario es una suma. El costo se congela.
No hay un contador de stock que alguien pueda editar. El saldo de cada lote es la suma de movimientos que nunca se modifican: una corrección es un reverso auditado, no un número sobrescrito. Cuando un pedido se despacha, el costo de cada lote que salió —café y empaques incluidos— queda congelado en esa línea y ya no cambia aunque mañana suba el café verde.
La misma idea separa a los dueños de cada dato: WooCommerce manda en el pedido web y el ERP es el único dueño del stock publicable. Nunca se importa stock desde la tienda, así que no hay bucles de sincronización.
Trazabilidad a la fincaCosto real, no estimadoUna sola fuente de stockLa IA propone, la persona aprueba
03El recorrido de un lote
De la finca al despacho.
Cada etapa deja movimientos en el mismo kardex y enlaza el lote nuevo con los lotes que consumió. Por eso una bolsa vendida se puede rastrear hasta el café verde del que salió, con el costo que aportó cada insumo.
Finca
Café verde con origenTostadora aliada
Tostión tercerizadaProducción
Receta aprobada · costo realKardex
Movimientos inmutablesWooCommerce
Pedidos webResend
Avisos del pedido
- 01
Compra a la finca
La recepción crea un lote de café verde con finca, variedad, proceso y origen, y un costo de llegada: precio por tasa de cambio más los gastos prorrateados.
- 02
Tostión externa
El verde sale hacia la tostadora y vuelve como tostado. El sistema calcula la merma y el costo por kilo útil: verde, transporte, tostión y otros, divididos entre lo que sí se puede empacar.
- 03
Producción
Una orden sobre una receta aprobada consume lotes por FIFO —FEFO para perecederos—, registra desperdicio y mano de obra valorizada, y cierra a costo real con una foto del costo planificado contra el real.
- 04
Pedido
Entra por WooCommerce, por WhatsApp, como venta manual o desde un evento o feria. Al confirmarse el pago, el stock se reserva; si un producto se hace bajo pedido, como el cold brew, la orden se produce en un solo paso.
- 05
Despacho
El stock se descuenta una sola vez y el costo de cada lote, con sus empaques, se congela en la línea. Se registran transportadora, guía y costo real de envío, y sale la etiqueta 4×6.
- 06
Avisos y rentabilidad
El cliente recibe los correos del recorrido del pedido, y el pedido entra a finanzas con su contribución: ingreso neto menos costo, comisión y subsidio de envío.
Las cifras de las capturas son del escenario de prueba del repositorio: 10 kg de verde, 8,5 kg útiles, 15 % de merma. Son datos inventados, no costos de Broo.
04Operación
Donde se forma el costo.
Dos pasos: despachar café verde y recibir tostado. La tabla deja a la vista lo enviado, lo útil, la merma y el costo por kilo tostado de cada orden. En el escenario de prueba, 10 kg salen y vuelven 8,5 kg: 15 % de merma.
Un cold brew de seis botellas: rendimiento medido, mano de obra en minutos y pesos, materiales consumidos y el costo real por unidad junto al planificado. Cada consumo es un movimiento inmutable atado a su lote.
La ficha de un lote de bolsas de 250 g guarda su costo congelado —materiales, mano de obra, procesos externos— y su genealogía: el tostado, la bolsa y la etiqueta que consumió y, un nivel más arriba, el café verde de Antioquia del que salió el tostado.
Cada cambio crea una versión nueva que debe aprobarse antes de producir. El sistema no trae recetas inventadas: ratio, extracción y rendimiento los carga el equipo.
El libro de movimientos: venta, salida y consumo de producción, con lote, cantidad y costo. Nada se edita; lo que se corrige se reversa con autor.
05El modelo de datos
Seis decisiones que no se ven.
89 tablas en 10 migraciones versionadas, separadas por dominio: identidad, compras, inventario, producción, comercial, CRM, marketing, finanzas, IA y archivos. Esto es lo que hace que los números cuadren.
El verde es un lote más.
Un lote de café verde no tiene tabla aparte: es un lote de materia prima enlazado a finca, variedad, proceso y origen. Por eso hay un único libro de movimientos para todo, del verde a la botella.
Saldo = suma.
Cada movimiento lleva una clave de idempotencia y, si corrige otro, el enlace al reverso. El inventario nunca queda negativo sin un permiso explícito.
Quién salió de quién.
Cada lote producido guarda los lotes que consumió, con cantidad y costo aportado. Rastrear una bolsa hasta la finca es recorrer esa relación hacia atrás.
Una foto, no un cálculo vivo.
La producción guarda el costo planificado contra el real; el despacho asigna lotes a cada línea con su costo y sus empaques. Si el verde sube mañana, lo vendido ayer no cambia.
Pesos y gramos exactos.
Dinero, cantidades y costos unitarios con decimales fijos y aritmética decimal, nunca flotantes. Unidades base en gramos, mililitros y unidades, y la masa nunca se convierte a volumen.
Solo se agrega.
Cada cambio de autorización por canal es una fila nueva; la última es la vigente. La historia de qué aceptó un cliente, y cuándo, no se pierde.
06Ventas y despacho
Lo que deja cada pedido.
El pedido muestra el lote del que salió cada artículo, su costo congelado y la cuenta completa: ingreso neto menos costo, comisión de pasarela y subsidio de envío, hasta la contribución y su margen. Los estados avanzan de pagado a despachado, con cancelaciones y devoluciones que no descuentan dos veces.
La etiqueta térmica sigue la plantilla de la marca: logo, número de pedido, artículos, quién envía y quién recibe. Se imprime sola o por lotes desde «Etiquetas por despachar», y el panel avisa si falta un dato antes de imprimir.
Cuatro avisos de servicio: pedido confirmado, despachado con guía, «¿Ya llegó?» con una receta corta según lo que compró, y «¿Qué tal tu café?» para pedir opinión. Cada paso sale una vez por pedido; los días se ajustan en parámetros.
07Canales y relación
Cada integración, con un oficio.
Pedidos sin bucles.
Importación incremental de productos, clientes y pedidos, webhooks firmados que se verifican y se deduplican, y un bloqueo por pedido para que un reenvío no impacte dos veces. Los pedidos anteriores a la salida en vivo entran como historia, sin tocar el stock.
Venta directa, mismo costo.
Los pedidos que no pasan por la web se crean en el panel con su canal, destinatario y despacho, y descuentan y cuestan igual que uno de la tienda. WhatsApp se abre con un clic; no hay envío automático.
Consentimiento por canal.
Perfiles, segmentos dinámicos que se recalculan a diario, exportación CSV solo de quien autorizó ese canal —protegida contra inyección de fórmulas— y anonimización para solicitudes de habeas data, que conserva los pedidos.
Correo que respeta límites.
Cola por lotes con topes diarios y mensuales, prioridad para los avisos del pedido, baja con un clic y supresión automática ante rebotes o quejas, a partir de eventos firmados.
Facturas y evidencias.
Adjuntos en PDF o imagen, hasta 4 MB, en compras, producción, lotes y pedidos. Se descargan solo con permiso de lectura sobre el registro al que pertenecen.
Mirar sin tocar.
Una vista de solo lectura de los flujos y sus ejecuciones dentro de Marketing, para revisar la automatización sin salir del panel.
08Finanzas
Facturación no es utilidad.
Ventas netas, costo por lote, contribución y utilidad operativa estimada, calculados desde pedidos, lotes y gastos. La cascada de la derecha baja del ingreso bruto a la utilidad renglón por renglón; los pedidos históricos quedan fuera.
Descuentos, alza de la materia prima, merma de tostión, envío y recompra contra CPA de equilibrio, CPA objetivo, ROAS de equilibrio y LTV. Se prellena con promedios observados, deja vacío lo que no tiene datos y se rotula como estimación, no como resultado.
09Inteligencia artificial
Un analista que lee, no que escribe.
El asistente usa Gemini con 7 herramientas fijas: cada una es una consulta SQL parametrizada y de solo lectura que escribimos nosotros. El modelo elige cuál usar y con qué fechas; nunca redacta SQL ni modifica un dato. Si un modelo responde con error o tarda demasiado, el servidor pasa al siguiente de una cadena de respaldo.
También propone borradores —correo, mensaje de WhatsApp, brief creativo, sugerencia de segmento, respuesta a un cliente y descripción de producto—, 6 tipos en total. Ninguno sale solo: queda esperando a una persona con permiso de aprobación y, al aprobarse, se convierte en una plantilla inactiva que alguien decide usar.
Las herramientas
- 01Indicadores del periodo
- 02Rentabilidad por SKU
- 03Estado del stock
- 04Desempeño de campañas
- 05Resumen de segmentos
- 06Sugerencias de reposición y cobertura
- 07Costos de las últimas producciones
Sin captura, a propósito
Las capturas de este caso se tomaron con la IA apagada. No mostramos una respuesta del asistente porque no vamos a fabricar una.
10Roles y permisos
Cinco roles, revisados en el servidor.
28 permisos granulares —ver, editar, aprobar recetas, autorizar inventario negativo, exportar, anonimizar, aprobar borradores de IA— repartidos en 5 roles. Cada página y cada acción del servidor exige el suyo: ocultar un botón nunca es la única barrera.
Todo el sistema.
Usuarios, parámetros, integraciones y auditoría. Es el único que puede anonimizar a un cliente.
Del verde al despacho.
Compras, tostión, inventario, producción y despacho de pedidos.
Clientes y campañas.
CRM, segmentos, plantillas, campañas y exportación con consentimiento.
Leer todo, decidir costos.
Lectura de todos los módulos salvo la auditoría, registro de gastos y escenarios, y edición del catálogo y sus precios.
Consultar sin cambiar.
Acceso de solo consulta para quien necesita ver el estado de la operación.
11Seguridad y privacidad
Cada acción, con autor.
La autenticación es propia y sin registro público: sesiones en base de datos con un token opaco que se guarda como hash, cookie httpOnly, bloqueo por intentos fallidos, enlaces de acceso de un solo uso que vencen en 48 horas y cambio obligatorio de contraseña cuando un administrador asigna una temporal.
Los errores de la base nunca llegan a la pantalla: se traducen a un mensaje y un código. Los webhooks se verifican con comparación de tiempo constante, las acciones relevantes quedan en un registro de auditoría y las herramientas de la IA devuelven datos agregados, no fichas de clientes.
El modelo
- 01Permisos en cada página y acción
- 02Sesión con token en hash
- 03Bloqueo por correo e IP
- 04Enlaces de acceso de un solo uso
- 05Webhooks firmados y deduplicados
- 06Cabeceras de seguridad estrictas
- 07Exportaciones a prueba de fórmulas
- 08Auditoría de acciones
12Sistema visual
La marca de la tienda, dentro del panel.
Acción primaria · Estado activo · Foco
- HEX
- #FF6A00
- RGB
- 255 · 106 · 0
Texto naranja sobre claro
- HEX
- #C24F00
- RGB
- 194 · 79 · 0
Barra lateral · Titulares · Gráficas
- HEX
- #062149
- RGB
- 6 · 33 · 73
Etiqueta «ERP» sobre navy
- HEX
- #C8915F
- RGB
- 200 · 145 · 95
Fondo de la aplicación
- HEX
- #FAF9F8
- RGB
- 250 · 249 · 248
Superficies secundarias · Hover
- HEX
- #F5F3F1
- RGB
- 245 · 243 · 241
13La entrada
Un panel interno con voz de marca.
Fondo navy animado en CSS y SVG —luz que se desplaza, vapor y grano—, sin JavaScript. Toda la animación del panel se apaga cuando el sistema pide movimiento reducido.
14Los principios
Vocabulario de la operación, no de software.
Mattone para titular, Kanit para leer.
El panel usa la display de broocafe.co en títulos y cifras, y Kanit en texto, tablas y formularios, con etiquetas en versalitas y números tabulares. En esta página los titulares van en Unbounded: la licencia de Mattone no está confirmada para usarla fuera del panel.
Si no hay dato, se dice.
Costos, recetas, impuestos y vida útil son parámetros que carga el equipo; el sistema no inventa ninguno. Una cifra sin base se marca «sin base» y un campo vacío del simulador no se rellena.
La guía de esta pantalla.
Cada pantalla tiene su guía, a un botón o a la tecla «?», y un centro de ayuda reúne los recorridos por módulo, de la puesta en marcha a la revisión semanal.
15Arquitectura
Reglas de negocio que se pueden probar.
Los servicios de dominio reciben la base de datos como parámetro y corren sin Next.js. Así las pruebas ejecutan el mismo SQL de producción contra un Postgres embebido, sin Docker.
Next.js 16
App Router · Server ActionsServicios
Reglas · permisos · auditoríaNeon Postgres
Drizzle · transaccionesCola de trabajos
Outbox · reintentosGemini
Solo lecturaVercel
Despliegue · almacenamiento
- 01
La interfaz
Next.js 16 con App Router, React 19, TypeScript y Tailwind CSS 4. Las mutaciones van por Server Actions que primero revisan el permiso.
- 02
El dominio
Un servicio por módulo valida, calcula con decimales exactos y escribe en una transacción, bloqueando las filas que podrían pisarse.
- 03
La base
Drizzle sobre Neon, con conexiones que soportan transacciones interactivas. En local y en pruebas, PGlite: el mismo Postgres, embebido.
- 04
Lo asíncrono
Una cola en Postgres con reintentos exponenciales, recuperación de trabajos atascados y un estado final para lo que no se pudo procesar. Integraciones y correo pasan por ahí.
- 05
La calidad
Más de 160 pruebas automatizadas contra Postgres real y 4 recorridos E2E sobre un build de producción. En cada cambio, CI verifica migraciones, lint, tipos, pruebas y build, sin secretos.
Resend envía el correo y Gemini responde al asistente; ambos se llaman solo desde el servidor. Las claves viven en el entorno del despliegue, nunca en el navegador.
16Evidencia de profundidad
Alcance técnico, no resultado comercial.
Cifras contadas sobre el repositorio. Describen el tamaño de lo construido, no ventas, horas ahorradas ni adopción, que se medirán cuando el sistema lleve tiempo operando.
- 28
- permisos en 5 roles, revisados en el servidor
- 89
- tablas en 10 migraciones versionadas
- +160
- pruebas automatizadas contra Postgres real
- 4
- recorridos E2E sobre un build de producción
- 7
- herramientas de IA de solo lectura
- ~8
- días del primer commit al sistema completo
17Estado real
Construido, probado y en operación inicial.
El primer commit es del 12 de octubre de 2026; el 19 el sistema ya tenía todos sus módulos, endurecimiento para operar, pruebas E2E y guías de uso. Compras, tostión, producción, inventario, ventas, etiquetas, CRM, recorrido del cliente, finanzas y asistente están construidos y verificados por pruebas.
Lo que sigue apagado lo está a propósito. La publicación de stock hacia WooCommerce espera a que el inventario físico esté conciliado; el disparador de n8n cada diez minutos está inactivo y, mientras tanto, corre un respaldo diario. Las automatizaciones de relación —bienvenida, recompra y recuperación— vienen inactivas hasta que la dueña las active, y el marketing por WhatsApp está oculto.
Los costos reales, la receta del cold brew y la tarifa de mano de obra todavía se están cargando, así que las cifras de rentabilidad se completarán con la operación. No hay punto de venta ni facturación electrónica: no estaban en el alcance.
Planeado o apagado
- 01Publicar stock en WooCommerce
- 02Disparador de n8n cada 10 minutos
- 03Automatizaciones de relación
- 04Marketing por WhatsApp
- 05Carga de costos reales y recetas
- 06Decisión sobre IVA y factura electrónica
18El resultado
Lo que cambia cuando el costo se ve.
Saber cuánto deja cada pedido.
Broo tiene una base para responder con datos lo que antes se estimaba: de qué finca salió el café de una bolsa, cuánto costó tostarlo y empacarlo, y cuánto quedó del pedido después del café, el empaque, la comisión y el envío.
Sobre esa base se decide el resto: cuánto invertir en pauta, qué reponer y a qué clientes escribir, siempre con una persona aprobando lo que sale.
TrazableCosteadoAuditado
→Proyecto relacionado
La tienda que alimenta este sistema.
beleafdesign
¿Sabes cuánto te deja cada pedido, o solo cuánto facturas?
Diseñamos sistemas a la medida que trabajan con lo que ya usas —tu tienda, tu correo, tus proveedores— y convierten la operación en números que se pueden revisar. Podemos mirar juntos cómo opera hoy tu negocio.
Hablemos de tu proyecto