27 de septiembre de 2026 · 3 min de lectura
Fineract sin fork: cinco patrones para extenderlo y seguir actualizándolo
Cómo agregar lógica propia, integraciones y reportes a Apache Fineract sin modificar el core, para que cada versión nueva de Apache sea un cambio de número y no un proyecto de migración.
La decisión de arquitectura más cara en una implementación de Fineract no se toma en un diagrama: se toma el día en que alguien abre el código del core, cambia una validación “solo esta vez” y hace build. Desde ese día la institución tiene su propio Fineract, y cada versión de Apache es un merge que nadie quiere hacer. Dos años después, el core está tres versiones atrás, sin los parches de seguridad, y “actualizar” es un proyecto de seis meses.
Estos cinco patrones existen para no llegar ahí.
1. Extensión por módulos
Fineract se construye con Spring Boot y desde la serie 1.8 está organizado en módulos que se cargan por classpath. Lo que no viene en el core (una validación regulatoria, un cargo que no existe, un job nocturno propio) se escribe como un módulo aparte que se despliega junto al core: mismo proceso, misma base de datos, cero cambios en el código de Apache.
Qué cabe en un módulo: listeners de eventos de negocio, command handlers nuevos, endpoints propios bajo un prefijo distinto, jobs programados, datatables con su lógica. Qué no cabe: cambiar cómo el core calcula intereses o aplica pagos. Si el producto exige eso, el producto está mal modelado y hay que volver al reglamento, no al código.
Cuando la lógica es grande o tiene otro ciclo de vida (un motor de scoring, un conciliador de pagos), va en un servicio separado que habla con el core por API. La regla de decisión es simple: si necesita transacción con el core, módulo; si no, servicio.
2. Un solo punto de entrada
Nadie llama a Fineract directamente. Un API Gateway (Kong, Apache APISIX, Envoy o el del proveedor de nube) queda delante del core y de los servicios propios. Ahí vive la autenticación con el proveedor de identidad (OIDC), el rate limiting por cliente, la auditoría de cada llamada y el versionado de rutas cuando la API del core cambia entre versiones.
El beneficio menos obvio: el portal, la app y los integradores externos ven una sola API estable aunque por detrás haya tres sistemas y la versión de Fineract cambie.
3. Eventos con outbox
Fineract emite eventos de negocio (LoanDisbursedBusinessEvent, SavingsDepositBusinessEvent y decenas más) y desde la serie 1.8 puede publicarlos externamente con un patrón outbox: el evento se escribe en una tabla en la misma transacción que el negocio, y un proceso aparte lo lleva al bus (Kafka, o una cola más simple) con reintentos.
Esto resuelve el problema que mata a las integraciones síncronas: si el sistema de notificaciones está caído cuando se desembolsa un crédito, el desembolso no falla y la notificación llega cuando el sistema vuelve. Ningún consumidor bloquea al core; ningún evento se pierde.
Consumidores típicos: notificaciones al cliente, conciliación con pasarela de pagos, alimentación de la bodega de datos, sincronización con el ERP contable.
4. Lectura separada de escritura
El core atiende transacciones. Los reportes gerenciales, la reportería regulatoria y los tableros de BI leen de otro lado: una réplica de solo lectura de la base de datos para lo operativo, y una bodega de datos alimentada por los eventos del punto 3 para lo analítico.
La razón no es solo rendimiento. Un reporte regulatorio de fin de mes que corre sobre la base transaccional compite con el cierre diario (COB) y con los jobs de devengo, y cuando compiten, lo que se pierde es la ventana de cierre.
5. Multi-tenant por diseño
Fineract es multi-tenant nativo: un despliegue atiende varios tenants con bases de datos separadas. Vale la pena usarlo aunque la institución sea una sola: producción, preproducción y un tenant de pruebas con datos anonimizados en el mismo despliegue, con la misma configuración, sin diferencias de ambiente que aparezcan el día de la salida.
Para grupos con varias entidades o fintechs con marcas blancas es directamente el modelo de negocio: un core, N instituciones, aislamiento de datos por construcción.
La prueba de fuego
Una implementación que sigue estos patrones actualiza Fineract así: cambiar la versión en el docker-compose, correr las migraciones de base de datos, ejecutar la batería de pruebas de productos (la hoja de cálculo que reproduce cada producto al centavo) y desplegar. Un día, a veces dos.
Si en su institución actualizar el core es un proyecto, alguno de los cinco patrones no se está cumpliendo. Casi siempre es el primero.