One Codebase, Many Banks

The problem. Many banks want the same mobile banking product. Each needs its own app in the stores, its own set of features, its own way of doing some things, and its own data kept apart. A separate app per bank would multiply cost and bugs with every new bank.

Our approach. One product, configured per bank:

• One app codebase and one backend codebase. A bank is a tenant pack for the app and a separate deployment of the backend.
• Features decided by the bank and the server, through five layers, down to the individual customer. A bank's "off" is final (how to switch a feature).
• Different flows without different code: settings, server-driven security steps and journey variants, never if (bank).
• Five update lanes, from a live switch in minutes to a store release in weeks. Every code change passes the bank's own UAT first.
• Operations built in: an admin portal with two-person approval, an audit log and monitoring for every bank.

Decided: one backend codebase, deployed separately for each bank. To decide: eight questions in section 15, starting with where each bank's backend runs.

Each bank is a separate customer with its own brand, products, rules and approval process. Differences appear at three levels:

Banks also want the same feature to work differently:

• One product, configured per bank. One app codebase and one backend codebase. A bank is a tenant pack for the app and a separate deployment of the backend.
• Bank differences are data. They live in tenant packs and server configuration, never in code branches.
• The server decides access and security. The app follows the server and never widens what it allows.
• Fail closed. An unknown feature, step or setting means off or stop.
• Every bank is isolated: its own app build, backend, data, keys, update channels, store listing and approvals.
• Every change has a lane. We use the fastest lane a change allows, and no code reaches a bank's customers without that bank's sign-off.

The backend follows the same rule as the app: one codebase and one versioned build, deployed separately for each bank and each environment. Banks differ only in configuration: their core-banking connection, database, keys, certificates and feature settings.

A tenant is one bank. It exists in four places, tied together by one id such as bank-b.

The pack is a typed file. The build fails if a field is missing.

Offboarding: switch the bank's features off live, unpublish its store listing with the bank, retire its two OTA channels, hand over or archive its data as the contract requires, shut down its backends, and remove the pack from the registry.

Every screen, tab, button and action has a feature key such as loans.apply. Keys form a tree: loans off hides everything under it. The app resolves each key through five layers, and a later layer overrides an earlier one, with one exception that protects the bank.

• The root key decides a module. Children default to on and are switched off only to remove one capability.
• New keys ship off. A CI check fails any new key that defaults to on without a written reason, so an update never shows a new feature to a bank that did not ask for it.
• The backend knows every key. CI publishes a feature catalog on each merge; each backend imports it, so the admin portal lists the same keys the app understands.
• The server checks again. Every endpoint maps to its feature key and refuses with FEATURE_NOT_AVAILABLE.
• Backend first, then switch on. A feature that needs a newer backend stays off for a bank until that bank's backend is upgraded. Each backend reports what it supports, and its config service never switches on a feature it cannot serve.

There are five places to switch a feature. Which one to use depends on who decides and for whom. Day to day, the bank admin portal is the normal way; the others are defaults, automatic rules or testing tools.

The bank's backend sends its decisions in one config reply. Bank-wide switches arrive at app start, on return to the app and at sign-in. The customer's own switches arrive after sign-in.

How the app decides

1. An unknown key is off.
2. If the bank or the session says off, it is off. Nothing can undo it.
3. If a parent is off (for example loans for loans.apply), it is off.
4. Otherwise, the most specific switch that has a value wins.

The switchboard (testing only). The switchboard lists every key with its current value and the reason, such as "turned off by the bank" or "parent is off". In UAT builds, testers can switch features on and off. In production builds it can only switch features off, it never undoes a bank's switch, and only staff the bank allows can open it.

What the customer sees when a feature turns off

• The tab or menu item disappears. There is no greyed-out button and no "coming soon" message.
• A customer already on that screen is taken back. During a payment, the app waits until the payment ends.
• Any remaining action is blocked in the app, and the server refuses it with FEATURE_NOT_AVAILABLE.

Making a new feature switchable

On the server, the loan-application endpoint maps to loans.apply and refuses the call while it is off. CI publishes the new key in the feature catalog, so it appears in every bank's admin portal.

When a bank wants a feature to work differently, we pick the lowest rung that fits. Each step up adds power and upkeep.

If the app decided "Bank B skips the TPIN", a modified app could skip it anywhere. So each bank's backend holds its policy and replies one step at a time: "now the TPIN", "now the OTP", "done".

The app never shows anything before it knows what this bank and this customer may use, and it never shows something the server would refuse.

Working locally, one bank at a time:

Rules for developers

• Never branch on the bank. Use a setting, the server policy, a journey variant, a strategy or a slot.
• Every new screen, tab, button and money action has a feature key, and the key ships off.
• Values a bank might change are settings, not constants.
• Security steps go through the flow framework, never a hand-written step machine.
• Test data lives in the dev environment only.
• Bank-specific code lives in that bank's pack, with a note in the pack's README saying why.

A feature is done when its key ships off; its route, UI and actions are gated; the server endpoint maps to the key; tests cover the flow; every CI check passes; the catalog is published; and the bank-facing notes are written.

• One image everywhere. Banks differ only in configuration and secrets: core-banking endpoint, database, key pair, certificates and org id.
• Infrastructure as code. One script creates a new bank's UAT and production backends. The target is one day per bank.
• Expand, then contract. Database and API changes are added first and removed later, so the previous backend version and older apps keep working during a rollout.
• Each backend reports itself. GET /meta returns its version and capabilities, and the release registry records which version each bank runs.
• Each backend serves one bank. It accepts only its own org id and refuses anything else.

Versions

• Each bank's app version lives in tenants/registry.json as MAJOR.MINOR.PATCH. A native release bumps MINOR; a native hotfix bumps PATCH.
• The store version code is computed: MAJOR × 10000 + MINOR × 100 + PATCH, so 1.6.2 becomes 10602.
• OTA bundles target exact native versions (-t 1.6.2), never wide ranges.
• We support the last two minor app versions; below that, the server's minimum version sends the customer to the store.

Signing and secrets

• One upload key per bank, stored only in CI secrets and backed up offline.
• Google Play App Signing per bank app; iOS certificates in each bank's Apple account.
• OTA credentials per environment; only CI may deploy to production channels.

Keeping app and backend compatible

• A bank's backend is upgraded before any app feature that needs it is switched on for that bank.
• API changes are additive. A field is removed only after every bank's backend and every supported app version have moved past it.
• The config response carries a schema version, and the app ignores keys it does not know.

OTA updates replace the app's JavaScript and images without a store release. Every bank has two channels: bank-x-uat, installed by its testers, and bank-x-prod, installed by its customers. The channel is baked into the app build, so a bundle for Bank B can never reach Bank A.

• Hotfix: the same path compressed into one day: a UAT smoke test within two hours, then 10% and 100% the same day.
• Rollback levels: automatic (crash before the first screen); disable one channel's bundle; disable a release on every channel with one script; then fix forward.
• A bank that has not signed off stays on its previous bundle. It may lag at most two trains before the release manager escalates.

Every crash report, API log and event carries five tags: tenant, appVersion, bundleId, configVersion and channel. Each bank's backend sends its metrics and logs, without customer data, to central monitoring. Thresholds below are starting points.

Support lookup: in the ops console, a support agent enters a customer's mobile number and sees the bank, app version, bundle, config version and every feature with the layer that decided it. The same resolution logic runs in the app and on the server, so both always agree.

Every change takes one of five lanes. The lane depends on what changed, not on urgency.

What keeps Bank B's change away from other banks

• A change only under tenants/bank-b/: CI detects it and rebuilds only Bank B's bundles.
• A change to shared code: every bank gets it in UAT, but each bank's production moves only after its own sign-off.
• A backend change or a switch: it happens in Bank B's own backend deployment. Other banks run separate deployments, and Bank B's admins cannot reach them.
• On the phone: the channel and the tenant guard stop any other bank's bundle from running.

1. The server is the boundary. Every business API checks the bank, the role and the customer again. App-side gating is for the customer's convenience.
2. Each bank's data stays in its own backend: a separate database, key pair and certificate per bank. The central platform holds no customer data.
3. HTTPS with per-bank certificate pinning, for config, security steps and every API. The PIN encryption key comes from the bank's backend, and pinning is what makes that key trustworthy.
4. Fail closed. An unknown feature key, challenge type or unreadable config means off or stop.
5. The bank's off is final. Session and device layers cannot re-enable it; release builds let the device layer switch features off only.
6. Kill switches survive offline, and the cached config only moves forward in version.
7. No leaks between customers or banks: session flags wiped at sign-out, a bundle per bank, the tenant guard, and token-scoped config.
8. Test data never ships. Mock data and test codes exist only in dev builds, and CI checks every release build.
9. Signed code: a store key per bank, signed OTA bundles, production deploys only from CI.
10. Crash reports without personal data, stored where the banks' data rules allow.
11. Every change recorded: two-person approval and an audit log for switches and policies.

The version support window (the last two app versions and at most two backend versions in production) is part of this proposal and needs the banks' agreement.