Construí un dashboard de analítica y recomendaciones para un programa de fidelización

Un enfoque minimalista para analytics y recomendaciones usando FastAPI, React y Docker

En el heatmap se puede verificar que el día y horario de mayor canje, es el jueves a las 11 AM

Los sistemas de fidelización suelen venir con bastante complejidad: bases de datos, pipelines de datos, modelos de machine learning, infraestructura…

Pero ¿qué pasa si solo tenés dos archivos CSV?

En este proyecto construí un dashboard completo de analítica y recomendaciones usando FastAPI, React y Pandas, sin base de datos y sin modelos entrenados para un prototipo.

A partir de datos de canjes y saldos de puntos, armé:

• Un dashboard de stock con métricas de concentración.
• Un dashboard de comportamiento de canjes (día × hora)
• Un motor de recomendaciones basado en co-ocurrencia de productos

Todo empaquetado en Docker y levantable con un solo comando.

🎯 El problema

Tenía dos fuentes de datos:

• Saldos de puntos por cliente
• Historial de canjes

Y quería responder preguntas bastante concretas:

• ¿Cómo está distribuido el stock de puntos?
• ¿Quiénes concentran más puntos?
• ¿Cuándo canjean los clientes?
• ¿Qué productos debería recomendarle a un cliente?

Sin armar una arquitectura compleja.

⚙️ Stack tecnológico (y por qué)

Elegí herramientas simples, rápidas y muy productivas:

Backend

• FastAPI + Pandas
• Sin ORM
• Sin migraciones
• Toda la lógica vive en memoria

Frontend

• React + Refine + Ant Design
• Estructura de dashboard lista
• Componentes reutilizables
• Desarrollo rápido

Visualización

• Plotly.js
• Interactividad sin esfuerzo
• Integración simple con React

Deploy

• Docker Compose
• docker compose up --build y listo

🏗️ Arquitectura

El sistema está pensado para ser simple y reproducible:

Frontend (React + Refine)
        │
        ▼
HTTP REST API
        │
        ▼
Backend (FastAPI + Pandas)
        │
        ▼
CSV (datos anonimizados)

👉 No hay base de datos 👉 No hay pipelines 👉 No hay jobs

Toda la analítica se calcula en memoria al iniciar la aplicación.

Esto está inspirado directamente en el repo:

📈 Dashboard 1 — Canjes

Acá el foco es comportamiento:

• KPIs generales
• Top productos
• Top rubros
• Evolución temporal

🔥 Lo más interesante

Heatmap día × hora

Permite detectar patrones como:

• picos de canje en horarios específicos
• diferencias entre días de la semana

📊 Dashboard 2 — Stock de puntos

Este dashboard responde: 👉 ¿Cómo están distribuidos los puntos?

Incluye:

• Total de clientes
• Total de puntos
• % de clientes sin puntos
• Top clientes por saldo

Como se distribuyen los puntos entre la base de clientes

🔍 Métricas clave

• Deciles de puntos
• Distribución por rangos
• Curva de concentración (tipo Gini)

Esto permite ver cosas como:

El 20% de los clientes concentra el 80% de los puntos

🤖 Dashboard 3 — Recomendaciones

Este es el corazón del proyecto.

Permite:

• Buscar por producto
• Buscar por cliente
• Ver recomendaciones en tiempo real
• Explorar pares de productos frecuentes

🧠 El algoritmo de recomendación

Acá está lo más interesante.

No hay modelos entrenados. No hay embeddings. No hay frameworks de ML.

Solo lógica simple y efectiva.

📌 Idea base: co-ocurrencia de productos

Si muchos clientes canjean:

Producto A + Producto B

Entonces:

👉 B es una buena recomendación para alguien que eligió A

🔄 Cómo funciona

1. Construcción del índice

client_id → {productos canjeados}

2. Recomendación por producto

Para un producto X:

1. Buscar clientes que canjearon X
2. Ver qué otros productos consumieron
3. Contar frecuencia
4. Ordenar

Resultado:

X → [Y1, Y2, Y3...]

al tipear o seleccionar cualquier producto, obtenemos recomendaciones

3. Recomendación por cliente

Para un cliente X:

1. Tomar todos los productos que ya consumió
2. Calcular co-ocurrencia para cada uno
3. Sumar scores
4. Excluir productos ya vistos

“Co-ocurrencia: personas similares consumen cosas similares”

4. Pares frecuentes

Contar:

(P1, P2)

para todos los clientes.

🧩 Ejemplo simple (mental)

Clientes:

C1 → A, B
C2 → A, C
C3 → A, B

Entonces:

• A → recomienda B y C
• B → recomienda A
• C → recomienda A

🧪 Endpoint clave (ejemplo)

El endpoint más interesante es:

GET /by_product?product=X&limit=N

Hace exactamente esto:

• filtra clientes que consumieron X
• cuenta productos asociados
• devuelve ranking

Simple, transparente y fácil de explicar.

🔐 Privacidad de datos

Para poder publicar el proyecto:

• IDs de clientes → hash SHA-256 truncado
• Productos → se mantienen (no son datos personales)
• Fechas y puntos → sin modificar

Esto permite:

👉 compartir datos reales sin exponer información sensible

🚀 Cómo ejecutarlo

Con Docker:

docker compose up --build

• Frontend: http://localhost:3000
• Backend: http://localhost:8010/docs

💡 Por qué este enfoque funciona

Este tipo de arquitectura tiene varias ventajas:

• Muy rápida de implementar
• Fácil de entender
• Ideal para prototipos o análisis exploratorio
• No requiere infraestructura compleja

Y lo más importante:

Genera valor e insights sin necesidad de modelos complejos

🔗 Repo Github

👉 GitHub: loyalty-points

🧠 Reflexión final

Muchas veces pensamos que para construir recomendaciones necesitamos:

• Machine Learning
• Modelos entrenados
• Pipelines complejos

Pero en muchos casos, especialmente en negocio:

👉 una buena heurística + buenos datos ya resuelve gran parte del problema y tenes un prototipo funcional.