Apache Fineract Consumer-Facing

Apache Fineract Consumer-Facing gives end users secure, authenticated access to Apache Fineract core banking functionality. It replaces the Self-Service APIs that were deprecated and removed from Fineract in 2025, which let client applications talk to Fineract Core directly.

The project was started in May 2026 as part of the Google Summer of Code (GSoC) program. It has two components:

• A Backend-for-Frontend (BFF): a Spring Boot service that is the only component allowed to talk to Fineract Core. It surfaces a curated, secured subset of Fineract functionality behind its own authentication, authorization, and audit layer.
• A consumer-facing frontend: a minimal Angular client that talks only to the BFF, never to Fineract directly. It exists to exercise the BFF endpoints end to end.

The client to BFF to Fineract boundary is the reason the project exists: the frontend never holds Fineract credentials, and the BFF is the policy enforcement point for all consumer-facing rules. The BFF keeps its own state (user accounts, refresh tokens, audit trail) in PostgreSQL; Fineract remains the system of record for banking data.

Requirements

• Java >= 21 (Azul Zulu JVM is tested by upstream Fineract CI on GitHub Actions)
• Node.js >= 22 and npm >= 10 (for the frontend)
• PostgreSQL >= 18 (the BFF keeps its own database, separate from Fineract's)
• Docker and Docker Compose (the bundled compose stack runs the BFF database, Fineract Core, a development SMTP server, and the BFF)

A running Apache Fineract Core instance is required for the BFF to call. The bundled Docker Compose stack provides one.

Security

The project exists because the previous direct-to-Fineract pattern was insecure. The BFF enforces:

• Deny-by-default authorization on every endpoint.
• Short-lived JWT access tokens (about 15 minutes) and rotating refresh tokens bound to a device fingerprint, so a refresh token stolen from another device fails.
• OTP verification on registration. OTP values are short-lived (about 5 minutes) and never logged.
• Attribute-Based Access Control (ABAC) combining principal, resource, and environment attributes before any call is delegated to Fineract.

Secrets and identity numbers are encrypted at rest and are never returned in API responses or written to logs.

Project Layout

The BFF is organized by feature and bounded context, not by layer. Feature services depend on narrow port interfaces; the Fineract Feign client is contained in the shared infrastructure package so Fineract stays swappable in tests.

fineract-consumer-facing/
├── consumer/                  Spring Boot BFF (Java 21, Gradle)
│   ├── src/main/java/org/apache/fineract/consumer/
│   │   ├── registration/          sign-up and account binding
│   │   ├── authentication/        login, tokens, password reset
│   │   ├── identity/              government-ID check against Fineract
│   │   ├── savings/               accounts, balances, transactions
│   │   ├── loans/                 accounts, schedules, applications, repayment
│   │   ├── transfers/             money movement between accounts and payees
│   │   ├── beneficiaries/         saved payees
│   │   ├── summary/               aggregated savings and loans dashboard
│   │   ├── openbanking/           OAuth2 consent and third-party read access
│   │   ├── user/                  profile and settings
│   │   ├── audit/                 audit event ingest and query
│   │   └── infrastructure/        cross-cutting: Fineract client, ABAC, JWT, OTP, rate limiting
│   ├── compose.yaml           backend stack (BFF, databases, Fineract, Mailpit, Valkey)
│   └── scripts/               dev key generation and demo seeding
├── frontend/                  Angular demo client (TypeScript)
│   └── src/
│       ├── app/features/          one folder per screen group, mirroring a BFF context
│       ├── app/core/              auth, interceptors, guards, audit, i18n, notifications
│       ├── app/shared/            reusable UI, OTP entry, shared styles
│       ├── app/layout/            shell for authenticated screens
│       └── openapi-client/        generated BFF client (alias @bff/client)
├── docs/                      AsciiDoc manuals
│   ├── consumer/                  BFF manual: architecture, security, features, appendix, diagrams
│   ├── frontend/                  Angular client manual: architecture, security, features
│   └── build.gradle               Asciidoctor build pipeline
├── docker-compose.e2e.yml     full stack including frontend, for E2E tests
└── .github/workflows/         CI: backend and frontend builds, CodeQL, RAT

The manuals under docs/ are built with Gradle. The Documentation section below has the commands and output locations.

Instructions

How to run the backend

The fastest way to bring up the whole backend stack (BFF database, Fineract Core, a development SMTP server, and the BFF) is Docker Compose.

# get code
git clone https://github.com/apache/fineract-consumer-facing.git
cd fineract-consumer-facing

# jwt local dev signing key generation
./consumer/scripts/generate-dev-jwt-key.sh

# start the backend stack
docker compose -f consumer/compose.yaml up -d

The BFF requires a JWT signing key (public/private) for asymmetrical signing with ES256. The bff service mounts one at /etc/bff/jwt-key.pem; for local Gradle runs the key location defaults to dev-jwt-key.pem. JWT Signing Key is generated automatically in CI and can be generated locally by invoking:

Once the stack is healthy, the services are available at:

• Consumer BFF: http://localhost:8080
• BFF API docs (Swagger UI): http://localhost:8080/swagger-ui.html
• Fineract Core: http://localhost:8888/fineract-provider
• Mailpit (development OTP inbox): http://localhost:8025
• BFF PostgreSQL: localhost:5432
• Fineract PostgreSQL: localhost:5433

How to run the frontend

cd frontend
npm install
npm start

The Angular development server runs on http://localhost:4200 and talks to the BFF.

How to run for local development

Run the entire e2e stack:

# start full e2e stack
cd frontend
npm run e2e:docker:up

The BFF reads configuration from environment variables with local defaults defined in consumer/src/main/resources/application.properties. The most relevant are:

• SPRING_DATASOURCE_URL (default jdbc:postgresql://localhost:5432/consumerapp) — the BFF database.
• FINERACT_BASE_URL (default http://localhost:8888/fineract-provider/api) — the Fineract Core API.
• FINERACT_SERVICE_USERNAME / FINERACT_SERVICE_PASSWORD (default mifos / password) — the BFF service account on Fineract.
• JWT_KEY_LOCATION (default file:dev-jwt-key.pem) — the JWT signing key.
• AUTH_ACCESS_TOKEN_TTL (default 15m) and AUTH_REFRESH_TOKEN_TTL (default 1d) — token lifetimes.

Testing

The backend uses JUnit 5 and Cucumber for end-to-end flows that have business meaning, such as registration, login, and ABAC denials.

Unit testing:

cd consumer
./gradlew test

E2E testing:

cd consumer
./gradlew cucumber

The frontend uses Vitest for unit tests and Playwright for end-to-end tests. The end-to-end suite runs against the full containerized stack defined in docker-compose.e2e.yml, which adds the frontend on top of the backend compose stack.

cd frontend
npm test                # unit tests
npm run e2e:stack:run   # bring up the stack, run Playwright, tear it down

Platform API

The BFF exposes a versioned REST API under /api/v1. When the BFF is running, the Swagger documentation can be accessed at http://localhost:8080/swagger-ui.html.

The openapi spec can be generated by:

cd consumer
./gradlew openapi

Openapi with Springdoc can be used to generate Typescript and Java Feign clients to target the BFF, or Java Feign clients to target Fineract:

BFF Java clients can be generated:

cd consumer
./gradlew generateJavaClient

BFF Typescript clients can be generated:

cd consumer
./gradlew generateTypescriptClient

Fineract clients can be generated:

cd consumer
./gradlew generateFineractClient

Documentation

The repository carries two AsciiDoc manuals under docs/. docs/consumer/ documents the BFF (architecture, security, features). docs/frontend/ documents the Angular client. Both compile to standalone HTML with AsciiDoctor through a Gradle subproject defined in docs/build.gradle and wired in through consumer/settings.gradle.

Unlike the other backend Gradle commands in this README, the documentation build needs no running Docker stack. It is pure file compilation: there is no live application to scrape.

The BFF manual can be built and opened:

cd consumer
./gradlew :docs:asciidoctor
open ../docs/build/docs/html/index.html

The frontend manual:

cd consumer
./gradlew :docs:asciidoctorFrontend
open ../docs/build/docs/html-frontend/index.html

Replace open with xdg-open on Linux or start on Windows. Those paths are relative to consumer/; from the repository root the manuals are at docs/build/docs/html/index.html and docs/build/docs/html-frontend/index.html.

The build uses strict validation. A broken include or a missing image fails the build rather than silently producing a broken page.

Community

This project is part of the Apache Fineract community. If you are interested in contributing, join the developer mailing list or the Fineract Slack channel. Issues are tracked on the Apache Fineract JIRA.

License

This project is licensed under the Apache License, Version 2.0.