Release Apache Fineract Backoffice UI 1.0.0

[Aman-Mittal]

Tracking issue for the first official release of the Fineract Backoffice UI, following the pattern other ASF projects use for a major release meta-issue (Airflow's Release Airflow 3.0 / Release Airflow 2.0 issues are the model).

This issue tracks the work. It does not replace the vote. Per ASF release policy the binding vote happens on dev@fineract.apache.org and needs three binding +1s from PMC members. Nothing here is authoritative until that thread passes.

Business Value

A release turns this repository into something an institution can adopt. Today there is no version anyone can name, no artifact anyone can download, and no published statement of what was tested — so a deployer evaluating it has to read the source and take the rest on trust. A released 1.0.0 gives them a fixed point: a version number, a signed source artifact with LICENSE and NOTICE, an SBOM, a dependency-licence report, and an honest list of what does and does not work against which Fineract version.

It matters to the project too. The UI already enforces route-level authorization, keeps navigation and route permissions from drifting apart in CI, and proves in its own tests that Fineract itself refuses what the UI refuses. None of that is visible to anyone who has not read the repository. A release is how that work becomes usable — and how the community gets a version to file bugs against instead of "main as of last Tuesday".

---

Status: READY FOR 1.0.0-RC.1 ONLY

A full release-readiness audit was run against 0846def1e7ce08cab809752f1808c2aa16b56f62. Every check below was executed on that commit and observed; none is inferred from a green CI badge.

The software is in good shape. The release engineering is what is missing, and every blocker is hours of work rather than weeks.

Verified green

Unit tests	1093/1093 + 2/2 (MFE project)
E2E	325 passed; 8 failures all attributed to host contention, green when re-run the way CI runs them (12/12 and 3/3)
E2E — two-factor, real backend	3 passed on a dedicated stack
GA gates	8/9, 0 blocking — the single advisory failure is an internal refactor counter that only has to fall
Build, lint, format, i18n, icons, internal endpoints, route permissions, e2e typecheck, licence headers	all pass
Apache RAT 0.17	706 approved, 0 unapproved — and the gate was proved to exit 1 on a real violation rather than taken on trust
Production dependency licences	26/26 ASF Category A (22 MIT, 2 Apache-2.0, 1 BSD-2-Clause, 1 0BSD)
Production vulnerabilities	0 (npm audit --omit=dev)
Permission codes	223 declared, 223 real — validated against the platform's own 699-code catalogue. None invented.
API contract currency	committed spec is operation-for-operation identical to Fineract head: 594 paths, 958 operations, 0 added, 0 removed
Supply chain	all 13 GitHub Actions SHA-pinned, least-privilege permissions, no pull_request_target, checksum-verified RAT download, dependabot + CodeQL + zizmor + a signed-commit gate
Coverage	73.7% statements excluding the generated OpenAPI client; every security-critical file ≥90%, guards and navigation config at 100%
Functional inventory	27 areas, 333 routes, 302 components, 0 TODO/FIXME/HACK, no dead routes, no placeholder screens

Blockers for a 1.0.0 tag

• V1 — the project has no version. package.json is 0.0.0, and it is not cosmetic: it reaches dist/…/remoteEntry.json as "version": "0.0.0" for every shared federation dependency, and the SBOM's metadata.component.version.
• D1 — no release documentation. No RELEASING.md, no changelog, no KEYS reference, no description of how a candidate is built, signed, staged or verified. For a first release, where the PMC votes on the process as much as on the payload, this is the largest single gap.
• L1 — one Category X licence needs a PMC/Legal ruling. eslint-plugin-sonarjs@4.2.0 is LGPL-3.0-only. It is a direct devDependency wired into eslint.config.js, used only to lint, and absent from both the production dependency tree and dist/ — but it is named in package.json, which travels in a source tarball.
• E1 — the container cannot reach a backend, in either documented configuration. Verified by building and running the image: GET /api/v1/authentication returns 200 text/html, 7546 bytes — the SPA's own shell — because deploy/nginx.conf has no API proxy. The cross-origin alternative is blocked by the CSP that same file serves (connect-src 'self'). The README's own /api/ → proxy to Fineract example is not implemented in nginx.conf.
• E2 — deploy/docker-compose.yml defaults to a third-party public demo host. An ASF deployment artifact should not default to sending an operator's credentials to a server the project does not control.
• E3 — the image build ignores the lockfile. deploy/Dockerfile runs npm install, not npm ci — exactly what CI's "Dependency Integrity" job exists to forbid. A published image would not be reproducible from the lockfile the SBOM describes.

E1–E3 bind only if the release ships a container. For a source-only release they drop to P2 and the remaining blockers are V1, D1 and L1.

Decisions only the PMC can make

• Artifact scope — source tarball only, or source plus a convenience container? Attribution, E1–E3 and the Docker Hub question all follow from this, and nothing else can be finalised without it.
• The LGPL-3.0 lint dependency — acceptable as build-only tooling in a source release, or replace before an RC?
• Version number, and when the "not release-ready" notice in security.md comes out. That notice stays until the PMC says otherwise; the audit did not remove it.
• Target Fineract version. Everything today — the committed OpenAPI contract, the generated client, and the real-backend E2E suite — is validated against head (1.16.0-SNAPSHOT, git describe 1.15.0-303-gf4f927e). If the release should be retrospective to 1.15, that compatibility is currently unevidenced, and a compatibility job is needed before the vote.
• Approve a release manager.

Release checklist

• Set the version; add a CI assertion that the tag and package.json agree
• RELEASING.md + CHANGELOG.md
• RM signing key published and added to KEYS
• Resolve or defer E1–E3 per the artifact-scope decision
• Correct the copyright year in NOTICE and README.md (both read 2025)
• Fix security.md's configuration table — it places rbacEnabled in environment.ts as a build flag; it is a runtime config.json key
• Remove the broken GEMINI.md link from README.md
• Tag 1.0.0-RC.1, build the source tarball, sign (.asc), checksum (.sha512)
• Run RAT over the tarball, not the working tree — a RAT run over a git checkout is not evidence about the artifact
• Stage in dist.apache.org/repos/dist/dev/fineract/
• [VOTE] on dev@fineract.apache.org, ≥72 hours, 3 binding +1
• svn mv to release/, wait for mirrors, [ANNOUNCE]

Known limitations for the release notes

Three features are blocked by verified Fineract defects on PostgreSQL, not by UI gaps — see #376:

Item	What the platform does
GLIM	creation fails: null value in column "principal_amount" of relation "glim_accounts" violates not-null constraint
GSIM	accepts the request, answers gsimId: 0, forms no parent record
Centre collection sheet	command=generateCollectionSheet → 500, operator does not exist: boolean = integer

Also for the notes:

• Migration-affecting change. Previously an authenticated user could reach many screens by typing the URL. Protected routes now require the corresponding permission, so a user whose role lacks a code loses access to screens they could previously open. This is intended, and it matches what the backend was already refusing. rbacEnabled: false in config.json restores the previous behaviour for a deployment that needs to stage the change.
• Hindi and Korean are 20.9% translated — 459 keys each against 2200 in en.json. Untranslated strings fall back to English rather than rendering as raw keys (verified), but the application offers three languages and delivers one.
• One WCAG 2.1 AA contrast failure. --ion-color-primary: #3498db with white text is 3.15:1 against the 4.5:1 requirement for normal-size text. That is arithmetic on the committed theme, not a flaky test. No WCAG compliance is claimed anywhere in the documentation, and that should stay true.

Evidence

The full audit report and its raw evidence are in audit/release-1.0.0/: the report itself, both CycloneDX 1.6 SBOMs (23 production / 932 full components), the licence reports, npm audit output, the RAT report, the platform permission catalogue as fetched, and every E2E and container-build log.

On attachments: GitHub's API cannot upload files to an issue — attachments require a browser upload. The SBOM and logs therefore need to be either dragged into a comment by hand, committed under audit/, or published as release assets. Flagging that rather than leaving it implied. Demo videos are not yet recorded; npm run demo:record produces them under demo-recordings/.

---

Self-serve, and deliberately unassigned. Comment here to pick up any checklist item.

[Aman-Mittal]

Release scorecard — 0846def1

Area	Status	Evidence	Blocking?
Version / release metadata	FAILED	0.0.0, propagates to remoteEntry.json and the SBOM; no release tags; no changelog	Yes (V1)
Build	VERIFIED	npm run build exit 0, 44 s	No
Lint	VERIFIED	npm run lint:prune exit 0	No
Format	VERIFIED	npm run format:check exit 0	No
i18n (mechanism)	VERIFIED	1532 referenced keys, 0 missing	No
i18n (locale completeness)	PARTIAL	hi/ko at 20.9%; English fallback confirmed	No
Unit tests	VERIFIED	1093/1093 + 2/2	No
Coverage	VERIFIED	73.72% statements excl. generated client; security-critical files ≥90%	No
E2E	VERIFIED	325 passed; 8 failures attributed to contention, green serially	No
E2E — two-factor	VERIFIED	3 passed, dedicated stack	No
RBAC	VERIFIED	223/223 codes real; drift checker passes; 50 RBAC e2e cases incl. backend refusal	No
Navigation authorization	VERIFIED	119 entries, 104 gated, static equality with routes enforced in CI	No
Action authorization	PARTIAL	163 gating sites; 62 of 74 write controls gated; 7 ungated, all leading to a gated route	No
API surface	VERIFIED	142 services / 564 operations; manifest matches; spec identical to Fineract head	No
GA gates	VERIFIED	8/9, 0 blocking	No
Dependency licensing (production)	VERIFIED	26/26 Category A	No
Dependency licensing (dev)	NEEDS A DECISION	eslint-plugin-sonarjs LGPL-3.0-only	Yes (L1)
Dependency vulnerabilities	VERIFIED	production 0; dev 11, none shipped, all fixable	No
ASF / RAT	VERIFIED	706 approved, 0 unapproved; gate proved to block	No
SBOM	VERIFIED (with limits)	CycloneDX 1.6, 23/932 components; no hashes — generator limitation, stated not fabricated	No
CI/CD security	VERIFIED	all actions SHA-pinned; no pull_request_target; least privilege	No
Accessibility	PARTIAL / one AA failure	axe passes on 4 screens; primary colour 3.15:1 vs 4.5:1	No
Functional coverage	VERIFIED	27 areas, 333 routes, 0 TODOs, no dead routes	No
Documentation	FAILED	no release docs; threat-model config table wrong; broken README link; stale copyright	Yes (D1)
Deployment artifacts	FAILED	image builds, but serves the SPA shell for /api/v1/*	Yes if a container ships
Breaking changes	VERIFIED	one, intended, with an opt-out	No
Release hygiene	FAILED	no tags, no changelog, no RM process, no KEYS	Yes (D1)

E2E attribution — why 8 failures are not 8 defects

The full suite was run on a fresh database against apache/fineract:latest:

bash scripts/e2e-stack.sh --fresh                              → exit 0
npx playwright test --project=mocked --project=backend         → 325 passed, 8 failed, 4 did not run (16.1 m)

This host has no CI env var, so Playwright used fullyParallel with default workers and retries: 0. CI sets workers: 1, retries: 2, and shards the mocked project four ways. Rather than assume, the failing specs were re-run the way CI runs them:

npx playwright test --project=backend --workers=1 \
  e2e/loan-lifecycle.spec.ts e2e/loan-schedule-type.spec.ts \
  e2e/share-account-servicing.spec.ts e2e/teller-cash-management.spec.ts
                                                               → 12 passed, exit 0

npx playwright test --project=mocked --workers=1 e2e/accessibility.spec.ts
                                                               → 3 passed, exit 0  (3.3 s/test vs 32–34 s under load)

Failure	Cause	Class
loan-lifecycle create/approve/disburse	select-popover option "outside of the viewport", retried 104× to a 120 s timeout	environment
loan-schedule-type progressive round-trip	seeded product not visible within 20 s	environment
loan-schedule-type badge	same popover signature, 150 retries	environment
share-account-servicing full lifecycle	activate control never appeared, 240 s	environment
teller-cash-management over-settlement	ensureCashMappings stayed on …/create; another spec created the mapping concurrently	test isolation under parallelism
accessibility × 3	axe color-contrast on a page in a transitional render state; all three also hit the 30 s test timeout	environment

None of the eight is a product defect. Two follow-ups fall out of it: teller-cash-management.spec.ts shares ensureCashMappings state and is not parallel-safe, and the accessibility gate is load-sensitive enough that it should not be the only AA check.

But the contrast defect the noisy run named is real

Under contention axe reported fgColor #ffffff, bgColor #3498db, contrastRatio 3.15, expectedContrastRatio 4.5:1. Those colours are not an artefact — they are the committed theme:

/* src/styles/_ionic-theme.scss */
--ion-color-primary: #3498db;
--ion-color-primary-contrast: #ffffff;

Computing the WCAG ratio from those two values gives 3.15:1. The test failures were environmental and the defect the test named is real; both are true and neither cancels the other.

[Aman-Mittal]

Staying current with Fineract, and the Docker Hub question

Answering the two engineering questions raised alongside this release.

1. Does the UI stay current with the head of Fineract main?

Today, yes — and this was verified rather than assumed. The spec inside the running apache/fineract:latest container was extracted and diffed against the committed contract:

committed public/api/fineract.json   info.version 1.16.0-SNAPSHOT | paths 594 | operations 958
spec inside apache/fineract:latest   info.version 1.16.0-SNAPSHOT | paths 594 | operations 958
operations in head but not committed:  0
operations committed but gone from head: 0

.github/workflows/api-spec-sync.yml is what keeps it that way: weekly, resolves apache/fineract:latest to a digest, short-circuits if the digest has not moved, otherwise reads the spec out of the image without booting Fineract, regenerates the client, writes a provenance record, and opens a PR. permissions: {} at workflow level. The real-backend E2E job also runs against latest, so behavioural drift is exercised on every PR, not just contract drift.

Of the platform's 958 operations the UI calls 564 across 142 services, pinned in src/app/core/adapters/api/api-surface.json and enforced by npm run api:surface in CI. Drift in either direction fails the build.

Three gaps worth closing:

#	Check	Why
1	Nightly E2E (real Fineract) on main	Head-drift is only exercised when someone opens a PR. A quiet week runs nothing.
2	Make the spec-sync compile-check failure loud in the PR body and job summary	Keep continue-on-error — an upstream removal must still open its PR — but a break should not read as green.
3	Daily rather than weekly sync	The digest short-circuit already makes an unchanged run cost seconds.

2. "The first release may need to be retrospective to 1.15"

This is the real gap, and nothing currently covers it. Everything above validates against head, and the committed spec reports 1.16.0-SNAPSHOT. Whether all 564 operations the UI calls exist in 1.15 is presently unknown.

#	Work	Why
4	scripts/check-api-compatibility.mjs <spec> — diff api-surface.json against a target Fineract spec, fail on any operation the UI calls that the target does not serve	The single most important unanswered question if 1.15 is the target. scripts/spec-diff-summary.mjs already has most of the machinery.
5	A compatibility-matrix E2E job running the backend project against a pinned apache/fineract:1.15.0	Contract compatibility is necessary but not sufficient; behaviour differs too.
6	A supported-versions table in the README, generated from whichever versions the matrix actually runs	So a deployer can see what was tested rather than infer it.

If 1.15 is the release target, item 4 should be green before the vote.

3. Deploying alongside Fineract on Docker Hub

The image builds — docker build -f deploy/Dockerfile . → exit 0, 107 MB — but is not deployable as shipped. Running it:

GET /                        → 200 text/html            (the SPA)
GET /config.json             → {"fineractApiUrl":"/api/v1", …}
GET /api/v1/authentication   → 200 text/html, 7546 bytes   ← the SPA shell, not Fineract

deploy/nginx.conf has no location /api/ proxy, so every API call falls through try_files to index.html. The alternative — the compose file setting an absolute cross-origin FINERACT_API_URL — is blocked by the CSP that same file serves (connect-src 'self', confirmed in the response headers).

Setting FINERACT_API_URL also reduces config.json from five keys to two:

before: fineractApiUrl, defaultTenant, rbacEnabled, institutionType, developerToolsEnabled
after:  fineractApiUrl, defaultTenant

ConfigService merges over its defaults, so rbacEnabled still lands true — this is not an RBAC bypass, and that was checked in source rather than assumed. But allowedApiOrigins (which backs a blocking GA security gate), institutionFeatures and nav overrides become unconfigurable in a container.

In order, before anything is published:

#	Work
7	Add the API proxy to deploy/nginx.conf so fineractApiUrl: "/api/v1" is same-origin and satisfies connect-src 'self'
8	Point the compose file at a local Fineract service, not a third-party demo host
9	npm ci in the Dockerfile; pin both base images by digest
10	Let the entrypoint merge config.json rather than overwrite it
11	A CI job that builds the image, runs it, and asserts GET /api/v1/… is proxied and not HTML
12	HEALTHCHECK, non-root nginx, drop the obsolete version: '3.8'
13	A publish workflow (tag → multi-arch build → provenance → Docker Hub), gated on the PMC vote

Item 11 is the one that matters most long-term: this audit found the proxy gap in ten minutes because it ran the container. CI never has.

4. On "the security setup is better than existing solutions"

That claim needs a defensible basis, so here is the evidence, all verified in this audit:

Property	This application
Route-level permission enforcement	Yes — permissionGuard on protected routes, returning a real Access Denied page rather than a silent dashboard bounce
Navigation/route drift prevention	Yes — a CI check that fails on disagreement and exits 1 rather than passing vacuously if it parses nothing
Permission codes validated against the platform catalogue	Yes — 223/223 real, checked against the live 699-code catalogue
Two-factor authentication	Yes, with a dedicated E2E stack and a mail catcher
CSP without unsafe-eval	Yes, shipped in deploy/nginx.conf
API-origin allow-list for endpoint override	Yes — a blocking GA gate
Authorization header restricted to the API origin	Yes — a blocking GA gate
No sanitizer bypasses or raw HTML sinks	Yes — a blocking GA gate
Production dependency vulnerabilities	0
Published threat model	61 KB, in-repo
Signed-commit enforcement on PRs	Yes
Backend refusal asserted in tests	Yes — E2E confirms Fineract itself refuses the restricted user's operation

The honest framing for a vote is "defence-in-depth the previous UI did not have, with Fineract Core still the authoritative boundary" — not "more secure". A frontend cannot be the security boundary, and DOCS/RBAC.md, security.md and the guard's own doc comment are already careful to say so. That framing should not be softened to make the release read better.

[Aman-Mittal]

gates-summary.txt
licenses-all.json
licenses-prod.json
npm-audit-all.json
npm-audit-prod.json
rat-report-0846def1.txt
sbom-full.cdx.json
sbom-prod.cdx.json

[Aman-Mittal]

Blocker L1 (the LGPL-3.0 devDependency) is addressed by #378, which removes eslint-plugin-sonarjs and replaces it with MIT/Apache-2.0 equivalents.

That changes the PMC question rather than answering it. The decision "is a build-only Category X dependency acceptable in a source release?" is no longer blocking this release, because there is no longer such a dependency — but it is still worth an answer on the dev list, since it will come up again on the next transitive bump.

#378 also turns the policy into a gate, so the next one fails CI rather than an audit:

Category A   PASS
Category B   REVIEW   reported for PMC awareness
Category X   BLOCK
Unknown      BLOCK    legal review

Current state over the whole tree: 1188 Category A, 7 acknowledged (BlueOak-1.0.0), 2 Category B (MPL-2.0, test-only), 0 Category X, 0 unclassified. Production alone is 25 packages, all Category A.

One item for the PMC comes out of that work rather than being resolved by it: BlueOak-1.0.0 is plainly permissive but is named in neither ASF category list. It is recorded in the script's ACKNOWLEDGED map, treated as Category A, and marked pending PMC confirmation — a written decision rather than a silent one. It reaches the tree only through build tooling (ESLint and the Angular CLI), so nothing distributed depends on the answer.

Cognitive complexity was preserved through the swap by implementing the rule locally at the same threshold, since nothing permissive on npm implements it. Details in the PR.

Remaining blockers on this issue are unchanged: V1 (version is 0.0.0), D1 (no release documentation), and E1–E3 if the release ships a container.

[Aman-Mittal]

#379 closes every remaining blocker that this repository can close on its own.

• V1 — version is 0.0.0 → 1.0.0-rc.1, with a check that a tag cannot disagree with package.json
• D1 — RELEASING.md and CHANGELOG.md added
• L1 — LGPL devDependency removed (chore(lint): remove the LGPL lint plugin, enforce ASF licence categories, run e2e on every push #378)
• E1 — container reaches Fineract; verified from a clean container, /api/v1/offices returns real JSON instead of the SPA shell
• E2 — compose brings up its own Fineract instead of defaulting to a third-party demo host
• E3 — image builds with npm ci, both bases pinned by digest
• E4 — entrypoint writes config.json whole, so no key is dropped
• E8 — a CI job builds the image, runs it against a real Fineract, and asserts the API is proxied

Two things worth surfacing here rather than leaving in the PR.

A gate would have gone quiet. The GA headers gate reads the nginx server block. Renaming that file to a template would have turned the gate unknown — and unknown did not block. It is repointed, and ga-check.mjs now fails on an undetermined blocking gate. A check that cannot read its input has not said yes.

A correction to the audit. V1 claimed the version also reaches remoteEntry.json. It does not — those 0.0.0s are native-federation's internal chunk placeholders. The SBOM claim holds and is verified (pkg:npm/fineract-backoffice-ui@0.0.0 → @1.0.0-rc.1); the remoteEntry.json half was wrong and is withdrawn.

What is left, and it is all yours

Decision	Note
Artifact scope — source only, or source plus a container?	The container now works either way, so this is no longer blocked on engineering
Target Fineract version	Everything is validated against head. If the release is retrospective to 1.15, that compatibility is still unevidenced — the compatibility job proposed in the audit is not built yet, and it is the one remaining piece of work I would do before a vote if 1.15 is the answer
Final version number	1.0.0-rc.1 is a starting point, not a decision
Does the "not release-ready" notice come out?	Still in security.md, untouched
Release manager	Three binding +1s on dev@fineract.apache.org

Once #379 lands, the dev-list proposal can be about those five questions rather than about outstanding work.