Problema
Controlar las finanzas personales con información repartida entre distintas herramientas dificulta entender los hábitos de gasto, consultar el balance real y registrar compras a partir de tickets.
Solución
- Next.js + React para construir un panel web responsive desde el que consultar y gestionar la información financiera.
- NestJS + TypeScript para organizar el backend en módulos y exponer una API REST mantenible.
- PostgreSQL + Prisma para modelar y persistir los datos financieros de forma relacional y tipada.
- MCP + OpenClaw para consultar la información y registrar operaciones desde lenguaje natural, manteniendo la API como única fuente de verdad.
- Docker Compose para levantar el entorno de base de datos de manera reproducible durante el desarrollo.
Funcionalidades
- Registro y consulta de ingresos y gastos.
- Gestión de varias cuentas y categorías, con archivado y restauración sin perder el historial.
- Filtros de movimientos por fechas, tipo, cuenta, categoría, origen, importe y texto.
- Dashboard con saldo actual, ingresos, gastos, balance mensual, balance acumulado, gráficos y evolución temporal.
- Transferencias entre cuentas, incluyendo conversión EUR/USD y creación atómica de los movimientos vinculados.
- Tickets agrupados por comercio y categoría mediante
Receipt, con vista de actividades y paginación. - Consulta de cuentas, categorías, movimientos, transferencias, tickets, dashboard y tipos de cambio mediante tools MCP.
- Registro de movimientos, tickets y transferencias desde un host compatible con MCP, con confirmación humana e idempotencia.
- API REST documentada mediante Swagger.
- Validación global de DTOs, manejo centralizado de errores y configuración mediante variables de entorno.
Decisiones Técnicas
El proyecto separa el frontend, el backend y el servidor MCP en aplicaciones independientes. Next.js se encarga de la interfaz con App Router, CSS Modules, formularios validados y gráficos con Recharts, mientras que NestJS concentra la lógica de negocio y la API REST.
NestJS es la única capa autorizada para aplicar reglas de negocio y escribir en PostgreSQL. Prisma proporciona acceso tipado a la base de datos, utiliza Decimal para evitar errores de precisión monetaria y mantiene el modelo sincronizado mediante migraciones. Docker Compose completa el entorno local con PostgreSQL 16 y pgAdmin.
Las transferencias se modelan como una operación propia y generan de forma atómica un movimiento de salida y otro de entrada. Los tickets agrupan movimientos por categoría mediante Receipt, mientras que las operaciones externas usan externalId deterministas para evitar duplicados cuando OpenClaw reintenta una petición.
El servidor MCP funciona como un cliente HTTP de la API REST, sin acceder directamente a PostgreSQL. Expone tools para consultar cuentas, categorías, actividades, transferencias, dashboard y tipos de cambio, además de permitir registrar movimientos, tickets y transferencias con confirmación humana previa. Esta capa permite utilizar el gestor desde OpenClaw u otros hosts compatibles mediante lenguaje natural.
