# Per-Bank Flow Variations

Feature flags answer **"does this bank have the feature?"**
This document answers **"how does the feature work for this bank?"**

| | |
|---|---|
| **Status** | Proposal |
| **Extends** | [MULTI_BANK_ARCHITECTURE.md](MULTI_BANK_ARCHITECTURE.md) (tenant packs, feature layers, `/features/config`) |
| **Audience** | Mobile team, backend team, product |

---

## Contents

1. [The problem](#1-the-problem)
2. [What the code does today](#2-what-the-code-does-today)
3. [The variation ladder](#3-the-variation-ladder)
4. [Rung 1 — Bank settings](#4-rung-1--bank-settings)
5. [Rung 2 — Server-driven challenges](#5-rung-2--server-driven-challenges-security-flows)
6. [Rung 3 — Journey variants](#6-rung-3--journey-variants-non-security-flows)
7. [Rung 4 — Strategies](#7-rung-4--strategies-same-screens-different-logic)
8. [Rung 5 — Slot overrides](#8-rung-5--slot-overrides-last-resort)
9. [Not allowed — branching on the bank](#9-not-allowed--branching-on-the-bank)
10. [One config response](#10-one-config-response)
11. [Worked example: one transfer, three banks](#11-worked-example-one-transfer-three-banks)
12. [Folder layout](#12-folder-layout)
13. [Testing](#13-testing)
14. [Migration plan](#14-migration-plan)
15. [Checklist: a bank asks for a different flow](#15-checklist-a-bank-asks-for-a-different-flow)

---

## 1. The problem

Banks don't only buy different features. They often want **the same feature to work differently**:

| Feature | Bank A | Bank B | Bank C |
|---|---|---|---|
| Approve a fund transfer | TPIN → OTP | OTP only up to ₹5,000; TPIN → OTP above | Biometric → TPIN |
| Register a device | Mobile → SMS OTP → MPIN | Mobile → debit card + PIN → OTP → MPIN | Mobile → account no. + date of birth → OTP → MPIN |
| Add a payee | Verify name (penny drop) → save | Save → 24-hour cooling period | Save → OTP |
| PIN / OTP length | MPIN 4, OTP 6 | MPIN 6, OTP 6 | MPIN 4, OTP 4 |
| Loan application | Product → amount → employment → documents → review | Product → amount → documents → review | — (no loans) |
| Account number format | 15 digits | 14 digits | 12–16 digits |

**What must not happen:** `if (bank === 'B')` spread across screens. With N banks and M features that grows to N × M branches nobody can test. The same goes for per-bank Git branches or copied screens: every bug fix then has to be made N times.

---

## 2. What the code does today

Every multi-step flow runs its own hand-written step machine, with the order and the values hard-coded:

| Flow | Steps, hard-coded | Where |
|---|---|---|
| Transfer authorisation | `'review' \| 'tpin' \| 'otp'` — "IMPS needs the TPIN first" | [PaymentConfirmationScreen.tsx:40, :200](../src/modules/payments/screens/PaymentConfirmationScreen.tsx) |
| TPIN create | `'mpin' \| 'otp' \| 'tpin' \| 'exists'` | [TpinCreateFlow.tsx:30](../src/modules/payments/components/TpinCreateFlow.tsx) |
| TPIN reset | `'start' \| 'otp' \| 'tpin' \| 'notSet' \| 'stopped'` | [TpinResetFlow.tsx:36](../src/modules/payments/components/TpinResetFlow.tsx) |
| MPIN reset | `'mobile' \| 'otp' \| 'newMpin'` | [MpinResetFlow.tsx:39](../src/modules/auth/components/MpinResetFlow.tsx) |
| Registration | `navigate('VerifyOtp')` → `CreateMpin` | [RegisterScreen.tsx:142](../src/modules/auth/screens/RegisterScreen.tsx), [AuthNavigator.tsx](../src/navigation/AuthNavigator.tsx) |
| Stop payment | `'find' \| 'confirm' \| 'stopped'` | [StopPaymentScreen.tsx:56](../src/modules/services/screens/StopPaymentScreen.tsx) |

Hard-coded values a bank might need to change:

| Value | Where |
|---|---|
| `OTP_LENGTH = 6`, copied 3 times, plus `length={6}` | [PaymentConfirmationScreen.tsx:37](../src/modules/payments/screens/PaymentConfirmationScreen.tsx), [TpinCreateFlow.tsx:35](../src/modules/payments/components/TpinCreateFlow.tsx), [TpinResetFlow.tsx:41](../src/modules/payments/components/TpinResetFlow.tsx), [VerifyOtpScreen.tsx:210](../src/modules/auth/screens/VerifyOtpScreen.tsx) |
| `TPIN_LENGTH = 4` | [tpinValidation.ts:4](../src/modules/payments/utils/tpinValidation.ts) |
| `MPIN_LENGTH = 4` | [validation.ts:10](../src/utils/validation.ts) |
| `RTGS_MINIMUM = 200000` | [TransferToAccountScreen.tsx:40](../src/modules/payments/screens/TransferToAccountScreen.tsx) |
| `requireMpinOnLaunch`, `lockAfterBackgroundMs` | [appConfig.ts](../src/config/appConfig.ts) |

The flows themselves are well written: idempotency keys, careful error handling, and never retrying after a timeout. **The problem is only where the decisions live.** The refactor moves the decisions out of the screens and keeps all of that logic.

---

## 3. The variation ladder

There are five ways to let a bank differ. **Always use the lowest rung that fits.** Higher rungs are more powerful and cost more to maintain.

| Rung | What differs between banks | Mechanism | Lives in | Can change without OTA? | Example |
|---|---|---|---|---|---|
| **1. Settings** | A value | Typed `BankSettings` | Pack + server | ✅ Yes | RTGS minimum, lock timeout, PIN length |
| **2. Server-driven challenges** | **Security steps**: proving identity, approving money | Challenge chain: the server says what it needs next | Backend policy; the app only renders | ✅ Yes | TPIN → OTP vs OTP only |
| **3. Journey variants** | Which screens a **non-security** journey has, and in which order | Named step lists compiled into the app | Core registry; pack or server picks one | ✅ Picks among shipped variants | Loan application with or without the employment step |
| **4. Strategies** | Rules or integration, with the **same screens** | An interface with a default and per-bank implementations | Core default, pack override | ❌ OTA | Account-number validation, receipt format |
| **5. Slot overrides** | A **section or screen looks different** | Slot registry | Pack `overrides/` | ❌ OTA | Bank C's own Home header |
| ✗ | — | `if (tenant.id === …)`, forks, branches | **Never** | — | — |

```mermaid
flowchart TD
    Q0["A bank wants feature X to work differently"] --> Q1{"Only a number,<br/>length or on/off?"}
    Q1 -- yes --> R1["Rung 1 — Setting"]
    Q1 -- no --> Q2{"Is it a security step?<br/>PIN, OTP, biometric,<br/>approval, cooling period"}
    Q2 -- yes --> R2["Rung 2 — Server challenge policy"]
    Q2 -- no --> Q3{"Different steps or order<br/>in a journey?"}
    Q3 -- yes --> R3["Rung 3 — Journey variant"]
    Q3 -- no --> Q4{"Same screens,<br/>different rule or backend?"}
    Q4 -- yes --> R4["Rung 4 — Strategy"]
    Q4 -- no --> R5["Rung 5 — Slot override"]
```

---

## 4. Rung 1 — Bank settings

### 4.1 Contract

```ts
// src/tenant/settings.ts
export interface BankSettings {
  auth: {
    mpinLength: 4 | 6;
    requireMpinOnLaunch: boolean;
    lockAfterBackgroundMs: number;
  };
  payments: {
    tpinLength: 4 | 6;
    rtgsMinimum: number;
    payeeCoolingHours: number;
  };
  services: {
    chequeLeafOptions: number[];
  };
}

/** Today's values, so the first bank sees no change. */
export const DEFAULT_SETTINGS: BankSettings = {
  auth: { mpinLength: 4, requireMpinOnLaunch: true, lockAfterBackgroundMs: 30_000 },
  payments: { tpinLength: 4, rtgsMinimum: 200_000, payeeCoolingHours: 0 },
  services: { chequeLeafOptions: [25, 50, 100] },
};
```

OTP length is deliberately **not** a setting. Under rung 2 every OTP challenge carries its own `length`, so the app never has to know it in advance.

### 4.2 Layers

The same layering as feature flags:

```
DEFAULT_SETTINGS  →  tenants/<id>/settings.ts  →  server "settings" (in /features/config)
```

| Rule | Why |
|---|---|
| Every server value is checked against a schema: type and range. Invalid values are ignored and the layer below stays | A typo on the server must not break the app |
| **Security timeouts: the stricter value wins.** `lockAfterBackgroundMs` takes the *smaller* of pack and server | The server can tighten security live, but a bad value can never loosen it |
| Values the backend enforces (PIN lengths) must match the backend | The app draws the boxes; the server decides what is valid |

### 4.3 Usage

```ts
// before — TransferToAccountScreen.tsx
const RTGS_MINIMUM = 200000;

// after
const { rtgsMinimum } = useBankSettings().payments;
```

`useBankSettings()` re-renders on a config change, the same way `useFeature` does.

---

## 5. Rung 2 — Server-driven challenges (security flows)

### 5.1 Why the server must drive security steps

Security steps already have to be enforced by the server. If the **app** decides "Bank B skips the TPIN", a modified app can skip it at any bank. So the server decides, and the app only knows **how to show** each kind of challenge:

- Bank A vs B vs C differences live in **one place**: the bank's policy on the server.
- "Above ₹5,000 also ask for the TPIN" (step-up by amount) is a policy rule, with no app change.
- "New device in its first 24 hours → extra OTP" (per customer) is also a policy rule.
- A new bank with a new order of existing challenge types needs **no app release at all**.

### 5.2 Protocol

```
POST /fund-transfers/initiate      { requestId, mode, amount, payer, payee }
← { flowId, status: "CHALLENGE",
    challenge: { type: "TPIN", length: 4, attemptsRemaining: 3 } }

POST /flows/{flowId}/answer        { type: "TPIN", response: "<RSA-OAEP encrypted>" }
← { flowId, status: "CHALLENGE",
    challenge: { type: "OTP", length: 6, expiresAt: "…", attemptsRemaining: 3, sentTo: "••••••3210" } }

POST /flows/{flowId}/answer        { type: "OTP", response: "482913" }
← { flowId, status: "COMPLETED", result: { refId, custRefNo, txnStatus: "SUCCESS" } }
```

Possible `status` values:

| `status` | Meaning | App does |
|---|---|---|
| `CHALLENGE` | Needs one more proof | Shows that challenge |
| `CHALLENGE` + `errorCode` | Wrong answer, try again | Same challenge, with the error and attempts left |
| `ACTION_REQUIRED` | E.g. `TPIN_NOT_SET` | Leaves the flow (to Create TPIN), then the customer comes back and confirms again |
| `COMPLETED` | Done | Result screen |
| `FAILED` | Attempt over; nothing debited | Back to review, with the message |

Server-side policy per bank (illustrative):

```yaml
# Bank A
transfer: [{ challenges: [TPIN, OTP] }]

# Bank B — step-up by amount
transfer:
  - when: amount <= 5000
    challenges: [OTP]
  - challenges: [TPIN, OTP]

# Bank C
transfer: [{ challenges: [BIOMETRIC, TPIN] }]
```

A `BIOMETRIC` challenge must be verifiable by the server, not just a local fingerprint prompt. The server sends a `nonce`; the app signs it with a key that only biometrics can unlock (`react-native-biometrics` `createSignature`); the server checks the signature against the public key registered for that device. Today the app uses biometrics only to unlock the stored MPIN, so this challenge type is new work.

### 5.3 App side — types

```ts
// src/flows/challenges/types.ts
export type Challenge =
  | { type: 'TPIN' | 'MPIN'; length: number; attemptsRemaining?: number }
  | { type: 'OTP'; length: number; expiresAt?: string; attemptsRemaining?: number; sentTo?: string }
  | { type: 'SET_PIN'; pin: 'TPIN' | 'MPIN'; length: number }   // choose a new PIN + confirm
  | { type: 'BIOMETRIC'; nonce: string; prompt: string };

export type FlowStep<TResult> =
  | { status: 'challenge'; challenge: Challenge; error?: string }
  | { status: 'action'; action: 'CREATE_TPIN' | 'RESET_TPIN' }
  | { status: 'done'; result: TResult }
  | { status: 'ended'; message: string };

/** One security flow — transfer, add payee, TPIN create/reset, MPIN reset, registration. */
export interface AuthorisationFlow<TInput, TResult> {
  start(input: TInput): Promise<FlowStep<TResult>>;
  answer(challenge: Challenge, response: string): Promise<FlowStep<TResult>>;
  reset(): void;
}
```

### 5.4 App side — runner and renderer

```ts
// src/flows/challenges/useAuthorisation.ts
export function useAuthorisation<TInput, TResult>(flow: AuthorisationFlow<TInput, TResult>) {
  const [step, setStep] = useState<FlowStep<TResult> | null>(null);
  const [busy, setBusy] = useState(false);

  const run = async (pending: Promise<FlowStep<TResult>>) => {
    setBusy(true);
    try {
      setStep(await pending);
    } finally {
      setBusy(false);
    }
  };

  return {
    step,
    busy,
    start: (input: TInput) => void run(flow.start(input)),
    answer: (response: string) => {
      if (step?.status === 'challenge') void run(flow.answer(step.challenge, response));
    },
    cancel: () => {
      if (busy) return; // a request in flight cannot be called back
      flow.reset();
      setStep(null);
    },
  };
}
```

```tsx
// src/flows/challenges/ChallengeSheet.tsx
const CHALLENGE_VIEWS = {
  TPIN: PinChallenge,
  MPIN: PinChallenge,
  OTP: OtpChallenge,
  SET_PIN: SetPinChallenge,
  BIOMETRIC: BiometricChallenge,
} satisfies Record<Challenge['type'], ComponentType<ChallengeViewProps>>;

export const ChallengeSheet = ({ auth }: { auth: ReturnType<typeof useAuthorisation> }) => {
  if (auth.step?.status !== 'challenge') return null;

  const { challenge, error } = auth.step;
  const View = CHALLENGE_VIEWS[challenge.type];

  return (
    <AppModal visible onClose={auth.cancel} title={challengeTitle(challenge)}>
      <View challenge={challenge} error={error} busy={auth.busy} onSubmit={auth.answer} />
    </AppModal>
  );
};
```

| Rule | Why |
|---|---|
| An **unknown** challenge type (from a newer server) ends the flow: "Update the app to continue" | Fail closed — never skip a step the app cannot show |
| `PinChallenge` and `OtpChallenge` wrap the existing [CodeInput](../src/modules/auth/components/CodeInput.tsx) | The same look in every flow, built once |
| Pre-login flows (registration, MPIN reset) use a full-screen `ChallengeScreen` instead of the sheet; same flow object | Presentation is separate from the steps |

### 5.5 Adapters — refactor the app now, without waiting for the backend

The protocol in §5.2 is the target. **Today's API is different**: `initiate` takes the TPIN, returns `PENDING_OTP`, then `verify-otp` follows. An adapter makes today's API look like a challenge chain, so the app can move to the new structure immediately:

```ts
// src/modules/payments/flows/impsTpinOtpTransfer.ts
export const impsTpinOtpTransfer = (
  api: FundTransferApi,
  settings: BankSettings,
): AuthorisationFlow<TransferInput, FundTransferVerifyResult> => {
  let input: TransferInput | null = null;
  let transfer: FundTransferInitiateResult | null = null;
  let requestId: string | null = null;

  return {
    async start(next) {
      input = next;
      // Today's initiate needs the TPIN up front, so it is the first challenge.
      return { status: 'challenge', challenge: { type: 'TPIN', length: settings.payments.tpinLength } };
    },

    async answer(challenge, response) {
      if (challenge.type === 'TPIN') {
        requestId = requestId ?? uuidv4(); // kept across network retries — see below
        try {
          transfer = await api.initiate({ ...input!, requestId, tpin: response });
        } catch (error) {
          return mapInitiateError(error as ApiError, challenge, () => (requestId = null));
        }
        return transfer.status === 'PENDING_OTP'
          ? {
              status: 'challenge',
              challenge: {
                type: 'OTP',
                length: 6,
                expiresAt: transfer.otpExpiresAt,
                attemptsRemaining: transfer.attemptsRemaining,
              },
            }
          : { status: 'ended', message: 'IMPS could not verify this payee. Check the details and try again.' };
      }

      try {
        return { status: 'done', result: await api.verifyOtp(transfer!.transferId, response) };
      } catch (error) {
        return mapVerifyError(error as ApiError, challenge);
      }
    },

    reset() {
      input = null;
      transfer = null;
      requestId = null;
    },
  };
};
```

All of today's rules move into the adapter **unchanged**:

- **Idempotency key:** kept across `NETWORK_ERROR` and `REQUEST_TIMEOUT`, dropped on any definite answer.
- **Error mapping:**
  - `INVALID_TPIN` → same challenge with an error;
  - `TPIN_NOT_SET` → `action: CREATE_TPIN`;
  - `OTP_INVALID` → same challenge with `attemptsRemaining - 1`;
  - `OTP_EXPIRED` and `OTP_ATTEMPTS_EXCEEDED` → `ended`.
- **Never retry `verify-otp` after a timeout:** report it as pending.

Each bank picks its adapter in its pack. When the backend ships the generic protocol, banks move to `server-driven` one at a time:

```ts
// src/modules/payments/flows/index.ts
export const TRANSFER_AUTHORISATION = {
  'imps-tpin-otp': impsTpinOtpTransfer, // today's API
  'server-driven': serverDrivenTransfer, // §5.2 protocol
} as const;

// tenants/bank-a/index.ts
flows: { transferAuthorisation: 'imps-tpin-otp' },
```

### 5.6 What the screen becomes

`PaymentConfirmationScreen` keeps the review, the receipt mapping (`finishImps`) and "save payee if asked". The TPIN modal, the OTP modal, the step state, the countdown and the error switch all leave the screen:

```tsx
const auth = useAuthorisation(useTransferAuthorisation()); // adapter picked by the bank's pack

useEffect(() => {
  const step = auth.step;
  if (step?.status === 'done') finishImps(step.result);
  if (step?.status === 'action') navigation.navigate(step.action === 'CREATE_TPIN' ? 'CreateTpin' : 'ResetTpin');
  if (step?.status === 'ended') setNotice(step.message);
}, [auth.step]);

return (
  <ScreenShell …>
    {/* review card — unchanged */}
    <Button title="Confirm" onPress={guardFeature(FeatureKey.PAYMENTS_TRANSFER_SUBMIT, () => auth.start(transferInput))} />
    <ChallengeSheet auth={auth} />
  </ScreenShell>
);
```

### 5.7 Flows that move onto the same framework

| Flow | Challenges today | Becomes |
|---|---|---|
| Transfer authorisation | TPIN → OTP | `transferAuthorisation` |
| TPIN create | MPIN → OTP → new TPIN | `tpinCreate` (`MPIN`, `OTP`, `SET_PIN`) |
| TPIN reset | (session) → OTP → new TPIN | `tpinReset` |
| MPIN reset | mobile → OTP → new MPIN | `mpinReset` (pre-login, full screen) |
| Registration | mobile → OTP → MPIN | `registration` — Bank B's card + PIN step is just another challenge type |
| Add payee | validate → save | `payeeAdd` — cooling period / OTP per bank policy |

Five hand-written step machines become one runner, one sheet and a set of small adapters.

---

## 6. Rung 3 — Journey variants (non-security flows)

### 6.1 When

Use this when a bank wants **different steps in a journey that collects information**, and the server does not need to enforce the order. Examples: loan application, agent account opening, cheque book request, onboarding slides, KYC update.

### 6.2 Definition

```ts
// src/flows/journeys/types.ts
export interface JourneyStep<TDraft> {
  id: string;
  title: string;
  component: ComponentType<JourneyStepProps<TDraft>>;
  /** Skip for this draft — e.g. no employment step for a pensioner. */
  when?: (draft: TDraft) => boolean;
  /** Dropped when this feature is off — flags still narrow journeys per customer. */
  feature?: FeatureKey;
}

export interface JourneyDefinition<TDraft> {
  steps: JourneyStep<TDraft>[];
  submit: (draft: TDraft) => Promise<void>;
}
```

### 6.3 Variants live in core, banks choose

```ts
// src/modules/loan/journeys.ts
export const LOAN_APPLICATION_JOURNEYS = {
  standard: {
    steps: [productStep, amountStep, employmentStep, documentsStep, reviewStep],
    submit: submitLoanApplication,
  },
  'no-employment': {
    steps: [productStep, amountStep, documentsStep, reviewStep],
    submit: submitLoanApplication,
  },
} satisfies Record<string, JourneyDefinition<LoanDraft>>;
```

The bank's choice resolves through the same layers as flags: **server `variants` → pack `variants` → `'standard'`**.

```ts
// tenants/bank-b/index.ts
variants: { 'loans.apply': 'no-employment' },
```

| Rule | Why |
|---|---|
| The server can only **pick** a variant that is compiled into the app; an unknown name falls back to the pack's choice | The server cannot invent a flow the app has never been tested with |
| A new variant is a code change in core (reviewed, tested), then shipped by OTA | Variants stay shared — Bank D can reuse Bank B's |
| Steps are built from shared step components | A bug fixed in `documentsStep` is fixed for every bank |

### 6.4 Runner

`<JourneyRunner journey={…} />` holds the draft, renders the current step, and handles Back / Next and the stepper. [TransferStepper](../src/modules/transfer/components/TransferStepper.tsx) generalises into this: today it has five fixed labels; it would take them from `journey.steps`.

---

## 7. Rung 4 — Strategies (same screens, different logic)

### 7.1 When

Use this when the screens are the same but a **rule or an integration** differs: account-number format, own-bank detection, receipt layout, how a bank's backend shapes a response.

### 7.2 Contract

```ts
// src/tenant/strategies.ts
export interface BankStrategies {
  accountNumber: {
    validate(value: string): string | undefined; // error message, or undefined when valid
    mask(value: string): string;
  };
  /** Is this IFSC one of our own branches? Today: "Within BankCBS" is hard-coded. */
  isOwnBank(ifsc: string): boolean;
  receipt: {
    lines(result: TransferReceipt): ReceiptLine[];
  };
}

export const DEFAULT_STRATEGIES: BankStrategies = { /* today's behaviour */ };

// merged once, at startup
export const strategies: BankStrategies = { ...DEFAULT_STRATEGIES, ...tenant.strategies };
```

```ts
// tenants/bank-b/strategies.ts
export const strategies: Partial<BankStrategies> = {
  accountNumber: {
    validate: (v) => (/^\d{14}$/.test(v) ? undefined : 'Bank B account numbers have 14 digits.'),
    mask: (v) => `••••${v.slice(-4)}`,
  },
  isOwnBank: (ifsc) => ifsc.startsWith('BNKB'),
};
```

| Rule | Why |
|---|---|
| Small interfaces, one per concern | Easy to override one thing without copying the rest |
| Strategies never render UI | UI differences are rung 5 |
| Each override has unit tests in the pack | Bank-specific logic is tested where it lives |
| A strategy is **not** a security control | The server still validates; a strategy only improves the message |

---

## 8. Rung 5 — Slot overrides (last resort)

### 8.1 When

Use this when a bank wants a **section or a screen to look and behave differently**, and nothing below fits.

### 8.2 Slots

```ts
// src/tenant/slots.tsx
export interface SlotProps {
  'home.hero': SummaryCardProps;
  'login.footer': LoginFooterProps;
  'transfer.reviewSummary': ReviewSummaryProps;
}

export function Slot<K extends keyof SlotProps>({
  name,
  fallback: Default,
  ...props
}: { name: K; fallback: ComponentType<SlotProps[K]> } & SlotProps[K]) {
  const Override = tenant.overrides?.[name] as ComponentType<SlotProps[K]> | undefined;
  const Component = Override ?? Default;
  return <Component {...(props as SlotProps[K])} />;
}
```

```tsx
// shared code
<Slot name="home.hero" fallback={SummaryCard} {...summaryProps} />
```

```ts
// tenants/bank-c/index.ts
overrides: { 'home.hero': BankCHeroCard },   // tenants/bank-c/overrides/BankCHeroCard.tsx
```

Whole screens work the same way: navigators register `screenFor('PaymentConfirmation', PaymentConfirmationScreen)`.

| Rule | Why |
|---|---|
| Prefer a **section** slot over a whole screen | Smaller override, less to keep in sync |
| Same typed props as the default | Shared code does not know or care which one renders |
| Overrides still use `FeatureGate`, `useFeatureAction` and `guardFeature` | Flags and kill switches keep working |
| Each override has an owner and is reviewed every release | Overrides drift; someone must notice |
| A bank with more than 3 overrides is a warning sign | The difference probably belongs in a setting, variant or strategy |

The pack is bundled only into its own bank's app (Metro `@tenant`), so Bank C's override code never ships to Bank A.

---

## 9. Not allowed — branching on the bank

Not allowed in `src/`:
- `if (tenant.id === 'bank-b')`
- `switch (tenant.orgId)`
- per-bank Git branches
- copies of screens

ESLint enforces the first two:

```js
// .eslintrc.js
module.exports = {
  root: true,
  extends: '@react-native',
  rules: {
    'no-restricted-syntax': [
      'error',
      {
        selector:
          "BinaryExpression[operator=/^[!=]==?$/] > MemberExpression[object.name='tenant'][property.name=/^(id|orgId)$/]",
        message: 'Do not branch on the bank. Use a setting, challenge policy, journey variant, strategy or slot — see docs/BANK_FLOW_VARIANTS.md.',
      },
      {
        selector:
          "SwitchStatement[discriminant.object.name='tenant'][discriminant.property.name=/^(id|orgId)$/]",
        message: 'Do not branch on the bank. See docs/BANK_FLOW_VARIANTS.md.',
      },
    ],
  },
};
```

`src/tenant/` itself may read `tenant.id`, for the tenant guard and channel names. Allow that with an `overrides` entry for that folder.

---

## 10. One config response

Settings and variants ride on the same `/features/config` response as flags. They get the same caching, the same offline behaviour, the same org scoping and the same "drop what you don't recognise" rule:

```json
{
  "version": 44,
  "overrides":     { "loans": true, "cards": false },
  "roleOverrides": { "loans.apply": false },
  "settings":      { "auth.lockAfterBackgroundMs": 20000, "payments.rtgsMinimum": 200000 },
  "variants":      { "loans.apply": "no-employment" }
}
```

Challenge policy is **not** in this response. It lives only on the server and shows up step by step inside each flow (§5). The app never needs to know a bank's security policy in advance.

**Who answers which question:**

| Question | Answered by | Rung |
|---|---|---|
| Does this bank / customer have it? | Feature flags | — |
| How much, how long, how many? | Settings | 1 |
| Which security steps, in which order? | Server challenge policy | 2 |
| Which screens in this journey? | Journey variant | 3 |
| Which rule or integration? | Strategy | 4 |
| Which look? | Slot override | 5 |

---

## 11. Worked example: one transfer, three banks

**The app code is identical for all three banks.** Only data differs:

| | Bank A | Bank B | Bank C |
|---|---|---|---|
| Pack `flows.transferAuthorisation` | `server-driven` | `server-driven` | `server-driven` |
| Server policy | `[TPIN, OTP]` | ≤ ₹5,000: `[OTP]`; above: `[TPIN, OTP]` | `[BIOMETRIC, TPIN]` |
| Pack `settings.payments.tpinLength` | 4 | 6 | 4 |

```mermaid
sequenceDiagram
    autonumber
    actor C as Customer
    participant S as PaymentConfirmationScreen
    participant R as useAuthorisation + ChallengeSheet
    participant API as Backend (bank policy)

    C->>S: Confirm ₹3,000
    S->>R: start(transferInput)
    R->>API: POST /fund-transfers/initiate
    alt Bank B and amount ≤ 5,000
        API-->>R: CHALLENGE OTP (length 6)
    else Bank A, or Bank B above 5,000
        API-->>R: CHALLENGE TPIN (length 4 or 6)
        R->>C: PIN sheet
        C->>R: TPIN
        R->>API: answer TPIN (encrypted)
        API-->>R: CHALLENGE OTP
    else Bank C
        API-->>R: CHALLENGE BIOMETRIC (nonce)
        R->>C: biometric prompt → signs nonce
        R->>API: answer BIOMETRIC (signature)
        API-->>R: CHALLENGE TPIN
    end
    R->>C: next sheet (OTP or TPIN)
    C->>R: code
    R->>API: answer
    API-->>R: COMPLETED
    R-->>S: done(result) → TransactionSuccess
```

Bank B can change its threshold from ₹5,000 to ₹10,000 in its policy with no app release.

---

## 12. Folder layout

```
src/
├── flows/                          NEW — shared flow machinery
│   ├── challenges/
│   │   ├── types.ts                Challenge, FlowStep, AuthorisationFlow
│   │   ├── useAuthorisation.ts     runner
│   │   ├── ChallengeSheet.tsx      in-app presentation
│   │   ├── ChallengeScreen.tsx     pre-login presentation
│   │   └── views/                  PinChallenge, OtpChallenge, SetPinChallenge, BiometricChallenge
│   └── journeys/
│       ├── types.ts                JourneyStep, JourneyDefinition
│       └── JourneyRunner.tsx       generalised TransferStepper
├── modules/payments/flows/         impsTpinOtpTransfer, serverDrivenTransfer, payeeAdd, tpinCreate, tpinReset
├── modules/auth/flows/             registration, mpinReset
├── modules/loan/journeys.ts        loan application variants
└── tenant/
    ├── settings.ts                 BankSettings, DEFAULT_SETTINGS, useBankSettings
    ├── strategies.ts               BankStrategies, DEFAULT_STRATEGIES
    └── slots.tsx                   Slot, screenFor

tenants/bank-b/
├── index.ts                        + flows, variants, settings, strategies, overrides
├── settings.ts
├── strategies.ts
└── overrides/                      only if rung 5 is really needed
```

---

## 13. Testing

| What | How |
|---|---|
| Each `AuthorisationFlow` adapter | Table-driven: given these server answers → expect these `FlowStep`s. Port the current behaviour first (idempotency, every error code) so the refactor is proven safe |
| `ChallengeSheet` | Renders every challenge type; an unknown type ends the flow safely |
| Settings | Every pack's settings pass the schema; the stricter-wins merge for security timeouts |
| Journey registry | Every variant's steps have components; every bank's chosen variant exists |
| Strategies | Unit tests inside each pack |
| No branching on the bank | ESLint rule in CI |
| Per bank | UAT build per bank, smoke-test the flows that bank customises |

---

## 14. Migration plan

**Build rungs 1–3 now; add rungs 4–5 only when the first real case shows up.**

| Phase | Work | Size | Behaviour change |
|---|---|---|---|
| F1. Settings | `BankSettings`, `useBankSettings`; replace `TPIN_LENGTH`, `MPIN_LENGTH`, `RTGS_MINIMUM`, the `appConfig.security` values | 1 day | None |
| F2. Challenge framework | Types, `useAuthorisation`, `ChallengeSheet`, `PinChallenge` and `OtpChallenge` (from `CodeInput`) | 2 days | None |
| F3. Transfer on the framework | `impsTpinOtpTransfer` adapter built from `PaymentConfirmationScreen`'s logic; screen keeps review + receipt; adapter tests | 1–2 days | None — same API, same steps |
| F4. Other security flows | TPIN create/reset, MPIN reset, registration onto the framework; the duplicate `OTP_LENGTH` constants go away | 3–4 days | None |
| F5. Backend protocol | Generic challenge endpoints + per-bank policy; banks switch to `server-driven` one by one | Backend team | Per-bank flows, live |
| F6. Journeys, strategies, slots | Only when a bank needs one | As needed | Per bank |

F1–F4 change no behaviour for the current bank. They are pure refactors, provable by the adapter tests in F3.

---

## 15. Checklist: a bank asks for a different flow

Ask these in order and stop at the first "yes":

1. **Is it only a value?** → Add or change a setting (§4).
2. **Is it a security step** — PIN, OTP, biometric, approval, cooling period? → Change that bank's server policy (§5). Add a challenge type to the app only if the step is new to every bank.
3. **Is it different steps in a journey?** → Pick an existing variant, or add a new one to core (§6).
4. **Same screens, different rule or backend?** → Strategy in the bank's pack (§7).
5. **A section looks different?** → Slot override in the bank's pack (§8).

Write the decision and the reason in the bank's pack `README.md`, so the next developer knows why that bank differs.