ADR-004: Single frontend codebase for customer and back office¶
| Status | Accepted |
| Date | 2026-04-10 |
| Deciders | CTO, Head of Product, Head of Platform |
| Affects repos | bank-app |
Status¶
Accepted — 2026-03-23
Context¶
The bank needs a customer-facing application and a back office operational tool. Building and maintaining two separate applications doubles the front-end engineering surface, creates divergence in design systems, and means customer-facing features must be rebuilt for back office use. The back office needs a superset of the customer view, not a fundamentally different application.
Decision¶
A single React/Next.js application serves all user surfaces. Mode is determined at authentication by JWT role claims — the application bootstraps into customer mode or back office mode based on the authenticated user's role. Navigation structure, data density, visible fields, and available actions are all driven by role context from a React context provider. The underlying component library is shared across all modes.
Consequences¶
Positive - One codebase to maintain — no divergence between customer and ops UI - Back office gets the same real-time data as the customer view, plus operational context - Shared design system — consistent experience across all roles - Feature built once, available to all roles at the appropriate permission level
Negative / trade-offs - Role-scoped rendering adds complexity to component logic - Bundle must be optimised to keep customer-mode load time within NFR targets - Back office features must not accidentally expose in customer mode — requires rigorous testing
Constraints this creates for bank-app¶
- Mode must be resolved server-side from JWT claims — never client-side only
- API gateway enforces data scope — front-end permission checks are UX only, not security
- Customer mode bundle target: ≤ 500kb gzipped, TTI ≤ 2s on 4G (NFR-016, NFR-017)
- Zero divergence in component library between modes — shared primitives only (NFR-009)
- All agent actions in back office mode logged to audit trail (MOD-047)
Principles alignment¶
| Principle | Assessment | Notes |
|---|---|---|
| AP-001 KISS | ✓ | One codebase, one build, one deployment — fewer moving parts |
| AP-005 Customer driven | ✓ | Customer-mode performance targets enforced; shared design system means consistency |
| AP-007 Evolution | ✓ | Single codebase evolves together; no synchronisation between two separate apps |
| AP-009 Robust and serviceable | ✓ | One deployment to monitor and operate |
Perspectives¶
| Perspective | Assessment | Notes |
|---|---|---|
| Performance & Scalability | ✓ | Single optimised bundle; mode-split lazy loading available |
| Usability | ✓ | Consistent design system; customer UX not degraded by back office complexity |
| Evolution | ✓ | New capabilities built once; available to appropriate roles immediately |
| Support & Maintenance | ✓ | One codebase to debug, test, and deploy |
| Security | ✓ | Mode gated server-side; API gateway is the enforcement boundary |
| Resource | ✓ | One frontend team owns both surfaces; no synchronisation overhead |
See perspectives.md for how to use these evaluation lenses.
Signoff record¶
| Date | Name | Role | Status |
|---|---|---|---|
| 2026-04-10 | Ross Millen | CTO | Approved |
| 2026-04-10 | Ross Millen | Head of Architecture | Approved |
| 2026-04-10 | Ross Millen | Head of Data | Approved |
Capabilities¶
| Capability | Description | Relationship |
|---|---|---|
| CAP-029 | Immutable audit log | governed — every agent action in back office mode is logged before execution |
| CAP-073 | Dual-mode rendering engine (customer + back office) | enabled — JWT role claim drives mode; same component tree renders differently |
| CAP-074 | Role-scoped API gateway | enabled — API gateway is the security boundary enforcing data scope per role |
| CAP-075 | Shared UI component library | enabled — single component library shared across customer and back office modes |
| CAP-119 | Customer 360 view (back-office) | enabled — back office mode surfaces operational context the customer never sees |
| CAP-120 | Manual account action toolkit | enabled — agent action buttons are back office mode features |
Related decisions¶
| ADR | Title | Relationship |
|---|---|---|
| ADR-007 | Frontend framework — React/Next.js with Capacitor | implements the framework decision for this ADR |
| ADR-009 | Insights and data visualisation approach | back office dashboards use the same codebase as customer app |
All ADRs
Compiled 2026-05-22 from source/entities/adrs/ADR-004.yaml