FinanceOS MX API
API REST empresarial para administrar finanzas personales en el ecosistema financiero mexicano: cuentas, tarjetas, transacciones, presupuestos, préstamos e inversiones en una sola API.
- Java
- Spring Boot
- PostgreSQL
- Maven
El caso de estudio
- Problema
- En México la vida financiera de una persona se reparte entre bancos, fintechs, SOFIPOs y wallets, cada uno con su propia app y formato: no existe un lugar único donde consultar cuánto se tiene, cuánto se debe o cuánto se gastó.
- Solución
- Un monolito modular en Java 21 y Spring Boot 3 —17 módulos de negocio con dependencias en una sola dirección—, seguridad JWT stateless, PostgreSQL con migraciones Flyway, errores RFC 9457 y una regla no negociable: el balance nunca se modifica directamente, siempre es consecuencia de las transacciones.
- Resultado
- Roadmap completo (10 de 10 fases): autenticación, cuentas, tarjetas, transacciones, planeación, pasivos, inversiones y reportes, con OpenAPI/Swagger, CI en GitHub Actions y una fase final de autoauditoría de arquitectura, seguridad y cobertura.
Proceso
Proceso de desarrollo
El razonamiento detrás de las decisiones técnicas: por qué se eligió cada tecnología, qué retos surgieron y cómo se resolvieron.
- 01
Monolito modular, dependencias en una sola dirección
Cada contexto de negocio (cuenta, transacción, presupuesto, inversión…) vive en su propio módulo con controller, service, repository, DTO y excepciones propias; las entidades JPA nunca se exponen por la API. Antes de escribir código documenté convenciones, seguridad y modelo de datos, y cuando una validación exigía romper la dirección de las dependencias —como bloquear el cierre de cuentas consultando tarjetas— preferí descartarla antes que violar la arquitectura.
- 02
El dinero como invariante del dominio
El dinero siempre en BigDecimal, UUID generados por la aplicación, tiempos en UTC y todo cambio de esquema versionado con Flyway. La regla central: el balance de una cuenta solo cambia a través de un único punto de mutación interno que registra la transacción en el mismo paso, preservando la dependencia unidireccional transaction → account. Los valores derivados —presupuesto gastado, próximo cobro, rendimiento— se calculan en cada request y nunca se persisten.
- 03
Verificación en vivo, no solo tests
Cada fase cerraba corriendo el JAR real contra una base limpia y verificando con curl, además de las pruebas con JUnit 5 y Mockito. Esa práctica encontró los bugs que los tests enmascaraban —como una LazyInitializationException invisible bajo tests transaccionales— y la fase final fue una autoauditoría: dependencias prohibidas entre módulos, mappers con relaciones lazy, duplicación y revisión de seguridad. Las reglas de arquitectura no se cumplen solas; hay que auditarlas.
Repositorios
Commits
- V1
dd562c2Eduardola semana pasada
