Hormigah - Control Inteligente de Gastos Hormiga

Una aplicación web moderna para controlar esos pequeños gastos diarios que pasan desapercibidos pero que al final del año suman cantidades importantes. Incluye sistema de automatización con n8n para reportes mensuales inteligentes con IA.

Concepto: Gastos Hormiga

Los gastos hormiga son pequeños desembolsos cotidianos que individualmente parecen insignificantes, pero acumulados representan una parte considerable del presupuesto:

• Café diario: €2,50 × 365 días = €912 al año
• Delivery impulsivo: €12 × 2 veces/semana = €1,248 al año
• Taxis innecesarios: €7 × 3 veces/semana = €1,092 al año
• Suscripciones no usadas: €9 × 12 meses = €108 al año

Total: €3,360 al año en gastos "pequeños"

Screenshots

Dashboard Principal

La vista principal con métricas en tiempo real, gráficos interactivos y lista de gastos recientes.

Gestión de Gastos

Lista completa de gastos con filtros avanzados y funcionalidad CRUD completa.

Modales Interactivos (HTMX)

Formularios dinámicos que se abren sin recargar la página.

Agregar Gasto	Editar Gasto

Perfil de Usuario

Configuración personal y alertas automáticas para reportes mensuales.

Funcionalidades Clave

Acceso y Autenticación

Página de login con diseño limpio y profesional.

Gestión de Presupuesto

Modal para configurar presupuesto mensual y alertas automáticas.

Diseño Responsive

La aplicación se adapta perfectamente a dispositivos móviles con navegación optimizada y formularios táctiles.

Filtros Avanzados

Sistema de filtros inteligentes por período, categoría y monto.

Versión Mobile

La aplicación cuenta con un diseño completamente responsive que se adapta perfectamente a dispositivos móviles.

Interfaz Principal Mobile

Dashboard optimizado para pantallas pequeñas con navegación intuitiva.

Navegación Mobile

Menú hamburguesa con acceso rápido a todas las funcionalidades.

Acceso Mobile

Página de login optimizada para dispositivos táctiles.

Gestión de Gastos Mobile

Lista de gastos y formularios adaptados para móviles.

Lista de Gastos	Agregar Gasto

Configuración Mobile

Perfil de usuario y configuraciones optimizadas para móvil.

Modo Oscuro

La aplicación incluye un sistema completo de modo oscuro que se adapta a todas las pantallas y componentes.

Características del Modo Oscuro

• Toggle Inteligente: Botón en el header que cambia de icono según el tema activo
• Interfaz Adaptada: Todos los componentes, modales y listas se adaptan al tema oscuro
• Persistencia: Guarda la preferencia del usuario en localStorage
• Transiciones Suaves: Cambios fluidos entre temas con animaciones CSS
• 100% Responsive: Funciona perfectamente en desktop y móvil

Dashboard - Modo Oscuro

El modo oscuro mantiene la legibilidad y jerarquía visual en todas las pantallas.

Lista de Gastos - Modo Oscuro

Vista de lista completa con el tema oscuro aplicado.

Características Principales

Dashboard Inteligente

• Métricas en tiempo real con filtros por período
• Gráficos interactivos (dona y líneas) con Chart.js
• Auto-actualización sin recargar página (HTMX)
• Diseño responsive optimizado para móviles

Análisis Visual

• Distribución por categorías con colores personalizados
• Tendencias temporales para identificar patrones
• Proyecciones anuales automáticas
• Comparativas mensuales

Experiencia de Usuario

• Interfaz HTMX sin recargas de página
• Modales dinámicos para operaciones CRUD
• Auto-refresh en listas y métricas
• Navegación fluida entre secciones
• Modo oscuro con transiciones suaves

Funcionalidades Avanzadas

• Filtros inteligentes por fecha, categoría y monto
• CRUD completo con validación en tiempo real
• Sistema de categorías con colores personalizados
• Gestión de usuarios con autenticación segura
• Sistema de alertas de presupuesto automatizado
• API REST: Endpoints específicos para integración con n8n
• Reportes Automatizados: Generación mensual de reportes con IA
• Webhooks: Sistema de notificaciones automáticas

Tecnologías

Backend

• Django 5.2.3: Framework web robusto
• Django REST Framework: API REST para integración con n8n
• PostgreSQL: Base de datos para desarrollo y producción
• Python 3.12: Lenguaje base
• Gunicorn: Servidor WSGI para producción

Frontend

• HTMX: Interactividad sin JavaScript complejo
• Tailwind CSS: Framework de utilidades CSS
• Chart.js: Gráficos interactivos
• Alpine.js: Interactividad ligera

Infraestructura

• Docker: Containerización completa
• Nginx: Servidor web y proxy inverso
• n8n: Automatización de workflows y reportes mensuales con IA

Instalación

Requisitos Previos

• Docker y Docker Compose
• Git

Setup Rápido

# Clonar repositorio
git clone https://github.com/tu-usuario/hormigah.git
cd hormigah

# Configurar variables de entorno
cp .env.example .env.local

# Iniciar aplicación
docker-compose up -d

# Configurar Django
docker-compose exec web python manage.py migrate
docker-compose exec web python manage.py createsuperuser

# Crear categorías predeterminadas (8 categorías base)
docker-compose exec web python manage.py create_default_categories

Acceso

• Aplicación principal: http://localhost:8000/
• Panel de administración: http://localhost:8000/admin/

Estructura del Proyecto

hormigah/
├── apps/
│   ├── core/                     # Utilidades base y templates
│   ├── expenses/                 # App principal de gastos
│   │   ├── api/                 # API REST para n8n
│   │   │   ├── authentication.py # Bearer token auth
│   │   │   ├── serializers.py   # DRF serializers
│   │   │   ├── views.py         # API views
│   │   │   └── urls.py          # API endpoints
│   │   ├── models.py            # Category, Expense, Budget
│   │   ├── views.py             # Lógica de negocio web
│   │   ├── forms.py             # Formularios con validación
│   │   ├── utils/               # Utilidades modularizadas
│   │   ├── templates/           # Templates especializados
│   │   └── static/              # CSS y JS específicos
│   └── users/                   # Gestión de usuarios
├── config/                      # Configuración Django
│   ├── settings/                # Settings modulares
│   │   ├── base.py             # Configuración base + API REST
│   │   ├── local.py            # Desarrollo
│   │   └── production.py       # Producción
│   └── urls.py                 # URLs principales + API
├── static/                      # Archivos estáticos globales
├── docker-compose.yml           # Docker desarrollo
├── docker-compose.prod.yml      # Docker producción + n8n
├── Dockerfile                   # Imagen de la aplicación
└── requirements.txt             # Dependencias Python + DRF

Uso de la Aplicación

Dashboard Principal

• Métricas del período seleccionado
• Gráfico de distribución por categorías
• Tendencia temporal de gastos
• Lista de gastos recientes

Gestión de Gastos

• Agregar nuevo gasto (modal HTMX)
• Editar gasto existente (modal HTMX)
• Eliminar gasto (confirmación)
• Ver detalles completos

Filtros Avanzados

• Por período (Este mes, último mes, últimos 7/30 días)
• Por categoría (Café, Delivery, Transporte, etc.)
• Por rango de fechas personalizado
• Por rango de montos (min/max)

Sistema de Alertas y Reportes

• Alertas automáticas al alcanzar el 90% del presupuesto mensual
• Configuración por usuario (activar/desactivar)
• Reportes Mensuales Automatizados: n8n + OpenAI + Gmail
• API REST: Integración específica para n8n
• Análisis Inteligente: IA personalizada por usuario y período

Comandos Útiles

Desarrollo

# Iniciar servicios
docker-compose up -d

# Ver logs
docker-compose logs -f web

# Ejecutar migraciones
docker-compose exec web python manage.py makemigrations
docker-compose exec web python manage.py migrate

# Ejecutar tests
docker-compose exec web python manage.py test

# Acceder a Django shell
docker-compose exec web python manage.py shell

Producción con n8n

# Desplegar aplicación + n8n
docker-compose -f docker-compose.prod.yml up -d

# Ver estado de todos los servicios
docker-compose -f docker-compose.prod.yml ps

# Ver logs específicos
docker-compose -f docker-compose.prod.yml logs web
docker-compose -f docker-compose.prod.yml logs n8n

# Acceder a n8n
# http://tu-dominio.com:5678

API Testing

# Test endpoint usuarios activos
curl -H "Authorization: Bearer {token}" http://localhost:8000/api/users/active/

# Test endpoint usuario completo  
curl -H "Authorization: Bearer {token}" http://localhost:8000/api/users/1/complete/

# Verificar documentación API
curl http://localhost:8000/api/docs/

API REST (Django REST Framework)

La aplicación incluye 2 endpoints específicos desarrollados con Django REST Framework para que n8n pueda generar reportes automáticos.

Endpoints Disponibles

Listar Usuarios Activos

GET /api/users/active/
Authorization: Bearer {N8N_API_TOKEN}

Propósito: Obtener lista de usuarios elegibles para reportes automáticos

Retorna usuarios que:

• Tienen presupuesto configurado
• Tienen alertas por email activadas
• Han registrado gastos en los últimos 30 días

Obtener Datos Completos de Usuario

GET /api/users/{id}/complete/
Authorization: Bearer {N8N_API_TOKEN}

Propósito: Obtener todos los datos necesarios para generar reportes con IA

Retorna datos completos incluyendo:

• Información del usuario y presupuesto
• Historial completo de gastos
• Resúmenes mensuales y por categorías
• Estadísticas y tendencias

Documentación Interactiva

• Swagger UI: http://localhost:8000/api/docs/
• OpenAPI Schema: http://localhost:8000/api/schema/

Autenticación API

• Desarrollo: Token fijo en settings
• Producción: Token seguro via variables de entorno
• Tipo: Bearer Token personalizado

Automatización con n8n

Workflows Automatizados

El sistema incluye dos workflows principales de n8n para automatización completa:

1. Reportes Mensuales Automatizados

• Schedule Trigger: Se ejecuta automáticamente el día 1 de cada mes a las 9:00 AM
• Detección de Usuarios: Consume endpoint /api/users/active/ para obtener usuarios elegibles
• Análisis Individual: Para cada usuario consume /api/users/{id}/complete/ para obtener datos completos
• Filtrado Temporal: Procesa únicamente los gastos del mes anterior
• Análisis con IA: GPT-3.5-turbo genera reporte personalizado
• Envío por Email: Gmail con diseño HTML profesional

2. Alertas de Presupuesto (90%)

• Webhook Trigger: Activado cuando Django detecta que un usuario supera el 90% del presupuesto
• Procesamiento Inmediato: Recibe datos del usuario y presupuesto actual
• Envío de Alerta: Email inmediato via Gmail notificando el límite alcanzado
• Prevención de Gastos: Ayuda a evitar superar el presupuesto mensual

Características del Sistema IA

• Análisis Temporal Preciso: Solo analiza el mes anterior, no el actual
• Métricas Financieras: Total gastado, porcentaje del presupuesto usado
• Desglose por Categorías: Análisis detallado de cada tipo de gasto
• Recomendaciones Personalizadas: Sugerencias específicas del usuario
• Alertas en Tiempo Real: Notificaciones automáticas al alcanzar límites
• Diseño Profesional: Emails HTML con identidad visual corporativa

Funcionalidades Destacadas

• Auto-Refresh Inteligente: Las listas se actualizan automáticamente
• Interfaz Moderna: Modales HTMX sin cambiar de página
• Modo Oscuro Completo: Sistema de temas con interfaz adaptable
• Responsive Design: Optimizado para todos los dispositivos
• Sistema de Automatización Completo: n8n + API REST + IA
• Reportes Mensuales Automatizados: Análisis personalizado con GPT
• Integración Gmail: Emails HTML profesionales automáticos