{"id":29748072,"url":"https://github.com/jaolmos/hormigah-expense-tracker","last_synced_at":"2025-08-17T01:07:00.076Z","repository":{"id":301009770,"uuid":"1006668213","full_name":"Jaolmos/hormigah-expense-tracker","owner":"Jaolmos","description":"Aplicación web  para control de gastos hormiga con Django 5.2 + HTMX + Tailwind CSS. Dashboard interactivo, modales dinámicos, gráficos Chart.js, filtros avanzados, API REST, automatización n8n con IA, Docker y diseño responsive. Control eficiente de pequeños gastos diarios.","archived":false,"fork":false,"pushed_at":"2025-07-30T17:26:28.000Z","size":2829,"stargazers_count":7,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-10T16:46:34.596Z","etag":null,"topics":["chartjs","django","docker","docker-compose","expense-tracker","financial-management","htmx","personal-finance","python","web-application"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Jaolmos.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-22T18:55:56.000Z","updated_at":"2025-07-30T17:26:06.000Z","dependencies_parsed_at":"2025-06-24T18:38:20.743Z","dependency_job_id":null,"html_url":"https://github.com/Jaolmos/hormigah-expense-tracker","commit_stats":null,"previous_names":["jaolmos/hormigah-expense-tracker"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Jaolmos/hormigah-expense-tracker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jaolmos%2Fhormigah-expense-tracker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jaolmos%2Fhormigah-expense-tracker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jaolmos%2Fhormigah-expense-tracker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jaolmos%2Fhormigah-expense-tracker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Jaolmos","download_url":"https://codeload.github.com/Jaolmos/hormigah-expense-tracker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jaolmos%2Fhormigah-expense-tracker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270792335,"owners_count":24646102,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-16T02:00:11.002Z","response_time":91,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chartjs","django","docker","docker-compose","expense-tracker","financial-management","htmx","personal-finance","python","web-application"],"created_at":"2025-07-26T09:39:33.293Z","updated_at":"2025-08-17T01:07:00.037Z","avatar_url":"https://github.com/Jaolmos.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hormigah - Control Inteligente de Gastos Hormiga\n\nUna 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.\n\n![Django](https://img.shields.io/badge/Django-5.2.3-092E20?style=for-the-badge\u0026logo=django\u0026logoColor=white)\n![DRF](https://img.shields.io/badge/Django%20REST-Framework-092E20?style=for-the-badge\u0026logo=django\u0026logoColor=white)\n![Python](https://img.shields.io/badge/Python-3.12-3776AB?style=for-the-badge\u0026logo=python\u0026logoColor=white)\n![HTMX](https://img.shields.io/badge/HTMX-1.9-336791?style=for-the-badge\u0026logo=htmx\u0026logoColor=white)\n![Tailwind](https://img.shields.io/badge/Tailwind-3.4-06B6D4?style=for-the-badge\u0026logo=tailwindcss\u0026logoColor=white)\n![Chart.js](https://img.shields.io/badge/Chart.js-4.4-FF6384?style=for-the-badge\u0026logo=chartdotjs\u0026logoColor=white)\n![n8n](https://img.shields.io/badge/n8n-Automation-EA4B71?style=for-the-badge\u0026logo=n8n\u0026logoColor=white)\n\n## Concepto: Gastos Hormiga\n\nLos **gastos hormiga** son pequeños desembolsos cotidianos que individualmente parecen insignificantes, pero acumulados representan una parte considerable del presupuesto:\n\n- Café diario: €2,50 × 365 días = €912 al año\n- Delivery impulsivo: €12 × 2 veces/semana = €1,248 al año  \n- Taxis innecesarios: €7 × 3 veces/semana = €1,092 al año\n- Suscripciones no usadas: €9 × 12 meses = €108 al año\n\n**Total: €3,360 al año en gastos \"pequeños\"**\n\n## Screenshots\n\n### Dashboard Principal\nLa vista principal con métricas en tiempo real, gráficos interactivos y lista de gastos recientes.\n\n![Dashboard Principal](screenshots/desktop/dashboard-complete-desktop.png)\n\n### Gestión de Gastos\nLista completa de gastos con filtros avanzados y funcionalidad CRUD completa.\n\n![Lista de Gastos](screenshots/desktop/expense-list-desktop.png)\n\n### Modales Interactivos (HTMX)\nFormularios dinámicos que se abren sin recargar la página.\n\n| Agregar Gasto | Editar Gasto |\n|---------------|--------------|\n| ![Agregar Gasto](screenshots/desktop/add-expense-modal-desktop.png) | ![Editar Gasto](screenshots/desktop/edit-expense-modal-desktop.png) |\n\n### Perfil de Usuario\nConfiguración personal y alertas automáticas para reportes mensuales.\n\n![Perfil de Usuario](screenshots/desktop/user-profile-desktop.png)\n\n### Funcionalidades Clave\n\n#### Acceso y Autenticación\nPágina de login con diseño limpio y profesional.\n\n![Login](screenshots/desktop/login-desktop.png)\n\n#### Gestión de Presupuesto\nModal para configurar presupuesto mensual y alertas automáticas.\n\n![Presupuesto](screenshots/desktop/budget-modal-desktop.png)\n\n#### Diseño Responsive\nLa aplicación se adapta perfectamente a dispositivos móviles con navegación optimizada y formularios táctiles.\n\n#### Filtros Avanzados\nSistema de filtros inteligentes por período, categoría y monto.\n\n![Filtros Activos](screenshots/desktop/expense-filters-active-desktop.png)\n\n### Versión Mobile\n\nLa aplicación cuenta con un diseño completamente responsive que se adapta perfectamente a dispositivos móviles.\n\n#### Interfaz Principal Mobile\nDashboard optimizado para pantallas pequeñas con navegación intuitiva.\n\n\u003cimg src=\"screenshots/mobile/dashboard-mobile.png\" alt=\"Dashboard Mobile\" width=\"300\"\u003e\n\n#### Navegación Mobile\nMenú hamburguesa con acceso rápido a todas las funcionalidades.\n\n\u003cimg src=\"screenshots/mobile/mobile-menu.png\" alt=\"Mobile Menu\" width=\"300\"\u003e\n\n#### Acceso Mobile\nPágina de login optimizada para dispositivos táctiles.\n\n\u003cimg src=\"screenshots/mobile/login-mobile.png\" alt=\"Login Mobile\" width=\"300\"\u003e\n\n#### Gestión de Gastos Mobile\nLista de gastos y formularios adaptados para móviles.\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003cstrong\u003eLista de Gastos\u003c/strong\u003e\u003c/td\u003e\n\u003ctd\u003e\u003cstrong\u003eAgregar Gasto\u003c/strong\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003cimg src=\"screenshots/mobile/expense-list-mobile.png\" alt=\"Expense List Mobile\" width=\"300\"\u003e\u003c/td\u003e\n\u003ctd\u003e\u003cimg src=\"screenshots/mobile/add-expense-mobile.png\" alt=\"Add Expense Mobile\" width=\"300\"\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n#### Configuración Mobile\nPerfil de usuario y configuraciones optimizadas para móvil.\n\n\u003cimg src=\"screenshots/mobile/user-profile-mobile.png\" alt=\"User Profile Mobile\" width=\"300\"\u003e\n\n## Características Principales\n\n### Dashboard Inteligente\n- Métricas en tiempo real con filtros por período\n- Gráficos interactivos (dona y líneas) con Chart.js\n- Auto-actualización sin recargar página (HTMX)\n- Diseño responsive optimizado para móviles\n\n### Análisis Visual\n- Distribución por categorías con colores personalizados\n- Tendencias temporales para identificar patrones\n- Proyecciones anuales automáticas\n- Comparativas mensuales\n\n### Experiencia de Usuario\n- Interfaz HTMX sin recargas de página\n- Modales dinámicos para operaciones CRUD\n- Auto-refresh en listas y métricas\n- Navegación fluida entre secciones\n\n### Funcionalidades Avanzadas\n- Filtros inteligentes por fecha, categoría y monto\n- CRUD completo con validación en tiempo real\n- Sistema de categorías con colores personalizados\n- Gestión de usuarios con autenticación segura\n- Sistema de alertas de presupuesto automatizado\n- **API REST**: Endpoints específicos para integración con n8n\n- **Reportes Automatizados**: Generación mensual de reportes con IA\n- **Webhooks**: Sistema de notificaciones automáticas\n\n## Tecnologías\n\n### Backend\n- **Django 5.2.3**: Framework web robusto\n- **Django REST Framework**: API REST para integración con n8n\n- **PostgreSQL**: Base de datos para desarrollo y producción\n- **Python 3.12**: Lenguaje base\n- **Gunicorn**: Servidor WSGI para producción\n\n### Frontend\n- **HTMX**: Interactividad sin JavaScript complejo\n- **Tailwind CSS**: Framework de utilidades CSS\n- **Chart.js**: Gráficos interactivos\n- **Alpine.js**: Interactividad ligera\n\n### Infraestructura\n- **Docker**: Containerización completa\n- **Nginx**: Servidor web y proxy inverso\n- **n8n**: Automatización de workflows y reportes mensuales con IA\n\n## Instalación\n\n### Requisitos Previos\n- Docker y Docker Compose\n- Git\n\n### Setup Rápido\n```bash\n# Clonar repositorio\ngit clone https://github.com/tu-usuario/hormigah.git\ncd hormigah\n\n# Configurar variables de entorno\ncp .env.example .env.local\n\n# Iniciar aplicación\ndocker-compose up -d\n\n# Configurar Django\ndocker-compose exec web python manage.py migrate\ndocker-compose exec web python manage.py createsuperuser\n```\n\n### Acceso\n- **Aplicación principal**: http://localhost:8000/\n- **Panel de administración**: http://localhost:8000/admin/\n\n## Estructura del Proyecto\n\n```\nhormigah/\n├── apps/\n│   ├── core/                     # Utilidades base y templates\n│   ├── expenses/                 # App principal de gastos\n│   │   ├── api/                 # API REST para n8n\n│   │   │   ├── authentication.py # Bearer token auth\n│   │   │   ├── serializers.py   # DRF serializers\n│   │   │   ├── views.py         # API views\n│   │   │   └── urls.py          # API endpoints\n│   │   ├── models.py            # Category, Expense, Budget\n│   │   ├── views.py             # Lógica de negocio web\n│   │   ├── forms.py             # Formularios con validación\n│   │   ├── utils/               # Utilidades modularizadas\n│   │   ├── templates/           # Templates especializados\n│   │   └── static/              # CSS y JS específicos\n│   └── users/                   # Gestión de usuarios\n├── config/                      # Configuración Django\n│   ├── settings/                # Settings modulares\n│   │   ├── base.py             # Configuración base + API REST\n│   │   ├── local.py            # Desarrollo\n│   │   └── production.py       # Producción\n│   └── urls.py                 # URLs principales + API\n├── static/                      # Archivos estáticos globales\n├── docker-compose.yml           # Docker desarrollo\n├── docker-compose.prod.yml      # Docker producción + n8n\n├── Dockerfile                   # Imagen de la aplicación\n└── requirements.txt             # Dependencias Python + DRF\n```\n\n## Uso de la Aplicación\n\n### Dashboard Principal\n- Métricas del período seleccionado\n- Gráfico de distribución por categorías  \n- Tendencia temporal de gastos\n- Lista de gastos recientes\n\n### Gestión de Gastos\n- Agregar nuevo gasto (modal HTMX)\n- Editar gasto existente (modal HTMX)\n- Eliminar gasto (confirmación)\n- Ver detalles completos\n\n### Filtros Avanzados\n- Por período (Este mes, último mes, últimos 7/30 días)\n- Por categoría (Café, Delivery, Transporte, etc.)\n- Por rango de fechas personalizado\n- Por rango de montos (min/max)\n\n### Sistema de Alertas y Reportes\n- Alertas automáticas al alcanzar el 90% del presupuesto mensual\n- Configuración por usuario (activar/desactivar)\n- **Reportes Mensuales Automatizados**: n8n + OpenAI + Gmail\n- **API REST**: Integración específica para n8n\n- **Análisis Inteligente**: IA personalizada por usuario y período\n\n## Comandos Útiles\n\n### Desarrollo\n```bash\n# Iniciar servicios\ndocker-compose up -d\n\n# Ver logs\ndocker-compose logs -f web\n\n# Ejecutar migraciones\ndocker-compose exec web python manage.py makemigrations\ndocker-compose exec web python manage.py migrate\n\n# Ejecutar tests\ndocker-compose exec web python manage.py test\n\n# Acceder a Django shell\ndocker-compose exec web python manage.py shell\n```\n\n### Producción con n8n\n```bash\n# Desplegar aplicación + n8n\ndocker-compose -f docker-compose.prod.yml up -d\n\n# Ver estado de todos los servicios\ndocker-compose -f docker-compose.prod.yml ps\n\n# Ver logs específicos\ndocker-compose -f docker-compose.prod.yml logs web\ndocker-compose -f docker-compose.prod.yml logs n8n\n\n# Acceder a n8n\n# http://tu-dominio.com:5678\n```\n\n### API Testing\n```bash\n# Test endpoint usuarios activos\ncurl -H \"Authorization: Bearer {token}\" http://localhost:8000/api/users/active/\n\n# Test endpoint usuario completo  \ncurl -H \"Authorization: Bearer {token}\" http://localhost:8000/api/users/1/complete/\n\n# Verificar documentación API\ncurl http://localhost:8000/api/docs/\n```\n\n## API REST (Django REST Framework)\n\nLa aplicación incluye **2 endpoints específicos** desarrollados con Django REST Framework para que n8n pueda generar reportes automáticos.\n\n### Endpoints Disponibles\n\n#### Listar Usuarios Activos\n```\nGET /api/users/active/\nAuthorization: Bearer {N8N_API_TOKEN}\n```\n\n**Propósito**: Obtener lista de usuarios elegibles para reportes automáticos\n\n**Retorna usuarios que**:\n- Tienen presupuesto configurado\n- Tienen alertas por email activadas  \n- Han registrado gastos en los últimos 30 días\n\n#### Obtener Datos Completos de Usuario\n```\nGET /api/users/{id}/complete/\nAuthorization: Bearer {N8N_API_TOKEN}\n```\n\n**Propósito**: Obtener todos los datos necesarios para generar reportes con IA\n\n**Retorna datos completos incluyendo**:\n- Información del usuario y presupuesto\n- Historial completo de gastos\n- Resúmenes mensuales y por categorías\n- Estadísticas y tendencias\n\n#### Documentación Interactiva\n- **Swagger UI**: http://localhost:8000/api/docs/\n- **OpenAPI Schema**: http://localhost:8000/api/schema/\n\n### Autenticación API\n- **Desarrollo**: Token fijo en settings\n- **Producción**: Token seguro via variables de entorno\n- **Tipo**: Bearer Token personalizado\n\n## Automatización con n8n\n\n### Workflows Automatizados\n\nEl sistema incluye dos workflows principales de n8n para automatización completa:\n\n![Workflow de Reportes n8n](screenshots/n8n/reports-n8n.png)\n\n#### 1. **Reportes Mensuales Automatizados**\n- **Schedule Trigger**: Se ejecuta automáticamente el día 1 de cada mes a las 9:00 AM\n- **Detección de Usuarios**: Consume endpoint `/api/users/active/` para obtener usuarios elegibles\n- **Análisis Individual**: Para cada usuario consume `/api/users/{id}/complete/` para obtener datos completos\n- **Filtrado Temporal**: Procesa únicamente los gastos del mes anterior\n- **Análisis con IA**: GPT-3.5-turbo genera reporte personalizado\n- **Envío por Email**: Gmail con diseño HTML profesional\n\n#### 2. **Alertas de Presupuesto (90%)**\n- **Webhook Trigger**: Activado cuando Django detecta que un usuario supera el 90% del presupuesto\n- **Procesamiento Inmediato**: Recibe datos del usuario y presupuesto actual\n- **Envío de Alerta**: Email inmediato via Gmail notificando el límite alcanzado\n- **Prevención de Gastos**: Ayuda a evitar superar el presupuesto mensual\n\n### Características del Sistema IA\n\n- **Análisis Temporal Preciso**: Solo analiza el mes anterior, no el actual\n- **Métricas Financieras**: Total gastado, porcentaje del presupuesto usado\n- **Desglose por Categorías**: Análisis detallado de cada tipo de gasto\n- **Recomendaciones Personalizadas**: Sugerencias específicas del usuario\n- **Alertas en Tiempo Real**: Notificaciones automáticas al alcanzar límites\n- **Diseño Profesional**: Emails HTML con identidad visual corporativa\n\n### Funcionalidades Destacadas\n- **Auto-Refresh Inteligente**: Las listas se actualizan automáticamente\n- **Interfaz Moderna**: Modales HTMX sin cambiar de página\n- **Responsive Design**: Optimizado para todos los dispositivos\n- **Sistema de Automatización Completo**: n8n + API REST + IA\n- **Reportes Mensuales Automatizados**: Análisis personalizado con GPT\n- **Integración Gmail**: Emails HTML profesionales automáticos","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaolmos%2Fhormigah-expense-tracker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjaolmos%2Fhormigah-expense-tracker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaolmos%2Fhormigah-expense-tracker/lists"}