Skip to content

feat: expand IBAN workbench #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Raafet57 merged 1 commit into from
May 5, 2026
Merged

feat: expand IBAN workbench #10

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 18 additions & 16 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,15 @@ data.

## Modules

| Module | Route | Status | What it does |
| ------------------------------ | -------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Scrubber** | `/scrubber` | Available | Strip personally identifying fields from `pacs.*` / `camt.*` XML before sharing with peers or vendors. Produces a privacy-safe mapping summary. |
| **Storyteller** | `/storyteller` | Available | Turn a `pacs.002 / 004 / 008 / 009` or `camt.052 / 053 / 054` message into a plain-language narrative plus a structured field projection and quick insights. |
| **IBAN Validator & Explainer** | `/iban` | Available | Validate and explain an IBAN from the bundled SWIFT IBAN Registry-derived data. Breaks the value into country, check digits, BBAN, bank, branch, account, and national-check segments where the registry supports it. |
| **BIC Validator\*** | `/bic` | Demo | ISO 9362 syntax checks plus a tiny bundled snapshot lookup. **Demonstration only:** bundled BIC data is not accurate/current enough for production, routing, compliance, reachability, or payment decisions. |
| **CBPR+ Readiness Checker** | `/cbpr` | Available | Browser-only AppHdr / Document namespace / CBPR+ schema-profile coverage checks, plus UETR, BIC syntax, and IBAN syntax/checksum hints. Not a certified validator or MyStandards usage-rule engine. |
| **Payment Insights Lite** | `/insights` | Available | Local lifecycle insight over ACK/NACK, `pacs.*`, and `camt.*` files you provide. Groups files by identifiers in memory; not live payment tracking, VOP, reachability, or settlement monitoring. |
| Vault | — | Planned | Planned encrypted local export bundle: user-controlled download/import, no cloud vault, no server storage, and no persistent browser storage by default. Not built yet. |
| Module | Route | Status | What it does |
| --------------------------- | -------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Scrubber** | `/scrubber` | Available | Strip personally identifying fields from `pacs.*` / `camt.*` XML before sharing with peers or vendors. Produces a privacy-safe mapping summary. |
| **Storyteller** | `/storyteller` | Available | Turn a `pacs.002 / 004 / 008 / 009` or `camt.052 / 053 / 054` message into a plain-language narrative plus a structured field projection and quick insights. |
| **IBAN Workbench** | `/iban` | Available | Validate, build, catalogue, and trace provenance for IBANs from bundled SWIFT IBAN Registry-derived data. Builder computes MOD-97 check digits from exact-length BBAN fields; no live BIC, VOP, account existence, or reachability checks. |
| **BIC Validator\*** | `/bic` | Demo | ISO 9362 syntax checks plus a tiny bundled snapshot lookup. **Demonstration only:** bundled BIC data is not accurate/current enough for production, routing, compliance, reachability, or payment decisions. |
| **CBPR+ Readiness Checker** | `/cbpr` | Available | Browser-only AppHdr / Document namespace / CBPR+ schema-profile coverage checks, plus UETR, BIC syntax, and IBAN syntax/checksum hints. Not a certified validator or MyStandards usage-rule engine. |
| **Payment Insights Lite** | `/insights` | Available | Local lifecycle insight over ACK/NACK, `pacs.*`, and `camt.*` files you provide. Groups files by identifiers in memory; not live payment tracking, VOP, reachability, or settlement monitoring. |
| Vault | — | Planned | Planned encrypted local export bundle: user-controlled download/import, no cloud vault, no server storage, and no persistent browser storage by default. Not built yet. |

\*The BIC module intentionally does **not** perform live BIC Directory lookup,
current bank-directory enrichment, current SEPA reachability checks, SWIFT FIN
Expand Down Expand Up @@ -43,7 +43,9 @@ banned APIs or absolute-URL `fetch` calls appear under `src/`.

- **IBAN:** uses generated browser data derived from the curated SWIFT IBAN
Registry material available to the project, with deterministic metadata beside
the generated JSON.
the generated JSON. `/iban` exposes Validate, Build, Catalogue, and Provenance
panels; Build derives MOD-97 check digits locally from exact-length BBAN fields
and still does not perform account existence, VOP, live BIC, or reachability checks.
- **BIC:** uses a deliberately tiny, allowlisted demo snapshot plus source-snapshot
country-code evidence for shape feedback. It is snapshot-bound and not a
replacement for a current BIC Directory feed/update process.
Expand Down Expand Up @@ -93,8 +95,8 @@ pnpm verify # lint + format:check + typecheck + test + privacy/data ch
- Vite + React 18 + TypeScript strict mode
- Tailwind v3 with light fintech tokens in `src/index.css`, derived from
[`DESIGN.md`](./DESIGN.md)
- React Router for `/`, `/scrubber`, `/storyteller`, `/iban`, `/bic`, `/cbpr`, plus a `*`
fallback
- React Router for `/`, `/scrubber`, `/storyteller`, `/iban`, `/bic`, `/cbpr`,
`/insights`, plus a `*` fallback
- Vitest + Testing Library for unit/page tests
- Playwright for end-to-end smoke tests
- ESLint + Prettier
Expand All @@ -111,7 +113,7 @@ src/
version.ts # SUITE_VERSION constant (kept in sync with package.json)
components/
bic/ # BIC demo validator UI primitives
iban/ # IBAN validator/explainer UI primitives
iban/ # IBAN Workbench UI primitives
layout/
SuiteLayout.tsx # shell with skip link, header, outlet, footer
SuiteHeader.tsx # wordmark + primary nav
Expand All @@ -132,7 +134,7 @@ src/
lib/
bic/ # browser-only BIC syntax/demo snapshot helpers
cbpr/ # browser-only CBPR+ readiness checks + generated manifest
iban/ # browser-only IBAN validation/decomposition helpers
iban/ # browser-only IBAN validate/build/catalogue/provenance helpers
iso20022/ # Scrubber parsing/rewriting (no UI deps)
storyteller/ # Storyteller parsing + narrative builders
utils.ts # cn() helper
Expand Down Expand Up @@ -161,8 +163,8 @@ To deploy on any static host, the host must:

- Serve the contents of `dist/` from the site root.
- For unknown / deep-link routes (for example `/scrubber`, `/storyteller`,
`/iban`, `/bic`, `/cbpr`, or `/anything-else`), fall back to serving `index.html` so
React Router can resolve the route on the client. This is sometimes called
`/iban`, `/bic`, `/cbpr`, `/insights`, or `/anything-else`), fall back to serving
`index.html` so React Router can resolve the route on the client. This is sometimes called
"SPA fallback" or "rewrite all to index.html".
- Not require any server-side execution. There is no API.
- Preserve the privacy posture: no analytics injection, no remote logging, and no
Expand Down
57 changes: 13 additions & 44 deletions ROADMAP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,15 @@ the suite is browser-only, static-host friendly, and privacy-first.

## Shipped baseline

| Area | Status | Notes |
| --------------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Scrubber | Shipped | Browser-side ISO 20022 XML scrubbing for `pacs.*` and `camt.*` samples. |
| Storyteller | Shipped | Browser-side ISO 20022 narrative/field projection for supported `pacs.*` and `camt.*` messages, with compact operator summary export. |
| IBAN Validator & Explainer | Shipped | Offline validation/decomposition from bundled SWIFT IBAN Registry-derived data. This is the strongest presently shipped reference-data module for durable offline payment intelligence. |
| BIC Validator\* | Shipped as demo | ISO 9362 syntax/decomposition plus tiny bundled snapshot lookup. Demonstration only; data is not accurate/current enough for production decisions. |
| CBPR+ Readiness Checker | Shipped | Browser-only AppHdr / Document namespace / bundled CBPR+ schema-profile coverage checks plus UETR, BIC syntax, and IBAN syntax/checksum hints. Not a certified validator. |
| Payment Insights Lite | Shipped | Browser-only local lifecycle insight over ACK/NACK, `pacs.*`, and `camt.*` files the user provides. Not live payment tracking, VOP, reachability, or settlement monitoring. |
| raafetchoukri.com-derived design system | Shipped | `DESIGN.md` and Tailwind tokens align the app with the light fintech/practitioner UI direction. |
| Area | Status | Notes |
| --------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Scrubber | Shipped | Browser-side ISO 20022 XML scrubbing for `pacs.*` and `camt.*` samples. |
| Storyteller | Shipped | Browser-side ISO 20022 narrative/field projection for supported `pacs.*` and `camt.*` messages, with compact operator summary export. |
| IBAN Workbench | Shipped | Offline Validate, Build, Catalogue, and Provenance panels from bundled SWIFT IBAN Registry-derived data. Build computes MOD-97 check digits from exact-length BBAN fields; no live BIC, VOP, account-existence, or reachability claim. |
| BIC Validator\* | Shipped as demo | ISO 9362 syntax/decomposition plus tiny bundled snapshot lookup. Demonstration only; data is not accurate/current enough for production decisions. |
| CBPR+ Readiness Checker | Shipped | Browser-only AppHdr / Document namespace / bundled CBPR+ schema-profile coverage checks plus UETR, BIC syntax, and IBAN syntax/checksum hints. Not a certified validator. |
| Payment Insights Lite | Shipped | Browser-only local lifecycle insight over ACK/NACK, `pacs.*`, and `camt.*` files the user provides. Not live payment tracking, VOP, reachability, or settlement monitoring. |
| raafetchoukri.com-derived design system | Shipped | `DESIGN.md` and Tailwind tokens align the app with the light fintech/practitioner UI direction. |

## Recommended next steps

Expand All @@ -39,37 +39,7 @@ Acceptance criteria:
persistence introduced by the host configuration.
- README hosting notes are updated with the chosen target.

### 2. IBAN Workbench

Refine the next IBAN module from a narrow calculator into a single workbench
that consolidates validation, registry-supported building, and registry-derived
reference content.

Sub-capabilities:

- **Validate** — keep the shipped offline validation/decomposition, with
clearer empty/success/warning/error states.
- **Build** — assemble an IBAN from a country selector and registry-supported
BBAN components where the structure permits it. Generate IBAN check digits
with MOD97. Explain each step and show why unsupported countries/structures
are blocked.
- **Catalogue** — browse country IBAN/BBAN structures, sample IBANs, segment
labels, BBAN patterns, and registry-expressed national check digits. Link
catalogue entries back to Validate examples. (Absorbs the previously listed
BBAN Structure Explorer / Country Catalogue item.)
- **Provenance** — surface source-registry metadata, generated-at timestamp,
source hash, and registry/version label where available. Provenance copy must
state that no live bank or reference-data lookup is performed.

Non-goals (carried forward):

- No live bank lookup.
- No account-owner/name matching.
- No VOP.
- No live BIC enrichment.
- No guarantee that a domestic account exists or is open.

### 3. Shared provenance pattern
### 2. Shared provenance pattern

Promote the per-module provenance idea into a cross-module shared pattern
rather than an IBAN-only panel.
Expand All @@ -90,7 +60,7 @@ Acceptance criteria:
- The component does not introduce any network call beyond the existing
same-origin sample/data fetches.

### 4. Vault — encrypted local export bundle only
### 3. Vault — encrypted local export bundle only

Vault remains planned and unbuilt. The recommended design is **Option A: an
encrypted local export bundle**, not a cloud vault and not default browser
Expand Down Expand Up @@ -139,9 +109,8 @@ is approved:

1. Documentation and roadmap refresh.
2. Deployment target decision and static-host configuration.
3. IBAN Workbench (Validate + Build + Catalogue + Provenance).
4. Shared provenance pattern across modules.
5. Vault only as the reviewed encrypted-local-export-bundle design above.
3. Shared provenance pattern across modules.
4. Vault only as the reviewed encrypted-local-export-bundle design above.

## Unscheduled candidates

Expand Down
35 changes: 32 additions & 3 deletions e2e/iban.spec.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
import { expect, test } from "@playwright/test";

test("iban module validates a known-good GB sample", async ({ page }) => {
test("iban workbench validates a known-good GB sample", async ({ page }) => {
await page.goto("/iban");

await expect(page.getByRole("heading", { level: 1, name: /iban validator/i })).toBeVisible();
await expect(page.getByRole("heading", { level: 1, name: /iban workbench/i })).toBeVisible();
await expect(
page.getByText(/runs entirely in your browser\. nothing is uploaded\./i).first(),
).toBeVisible();
Expand All @@ -17,7 +17,9 @@ test("iban module validates a known-good GB sample", async ({ page }) => {
await expect(breakdown).toContainText("NWBK");
});

test("iban module flags a flipped check digit and shows what it does not do", async ({ page }) => {
test("iban workbench flags a flipped check digit and shows what it does not do", async ({
page,
}) => {
await page.goto("/iban");
const input = page.getByLabel("IBAN input");
await input.fill("GB28NWBK60161331926819");
Expand All @@ -31,3 +33,30 @@ test("iban module flags a flipped check digit and shows what it does not do", as
await expect(page.getByText(/no live bic/i)).toBeVisible();
await expect(page.getByText(/no live sepa/i)).toBeVisible();
});

test("iban workbench builds an IBAN from the bundled BBAN template", async ({ page }) => {
await page.goto("/iban");
await page.getByRole("button", { name: /build.*assemble an iban/i }).click();
await page.getByRole("combobox", { name: /build country/i }).selectOption("GB");
await page.getByRole("button", { name: /fill registry example/i }).click();

await expect(page.getByLabel(/built iban electronic/i)).toContainText("GB29NWBK60161331926819");
await expect(page.getByLabel(/computed check digits/i)).toContainText("29");
await expect(page.getByText(/No live bank, BIC, account-owner \/ VOP/i)).toBeVisible();
});

test("iban workbench catalogues bundled structures without live-reachability claims", async ({
page,
}) => {
await page.goto("/iban");
await page.getByRole("button", { name: /catalogue.*browse bundled country/i }).click();
await page.getByRole("textbox", { name: /search countries/i }).fill("United Kingdom");
await page.getByRole("button", { name: /GB · United Kingdom/i }).click();

await expect(page.getByText(/The SEPA flag here is the bundled registry/i)).toBeVisible();
await page.getByRole("button", { name: /validate this example/i }).click();
await expect(
page.getByRole("button", { name: /validate.*bundled registry snapshot/i }),
).toHaveAttribute("aria-pressed", "true");
await expect(page.getByLabel("IBAN input")).toHaveValue(/^GB/);
});
Loading
Loading