User Interface — Overview

The User Interface section documents how the Arda web application is structured and how it cooperates with the rest of the platform. The application is a single-page React app served by a Next.js Backend-For-Frontend (BFF) running inside the same Node process; the BFF holds the API credentials, terminates the user’s identity context, and proxies every functional request to the backend services.

This section is the home for the what-it-is reference. The catalogue under Architecture Patterns is the how-to-design catalogue and is a sibling, not a parent: pattern entries link here when a frontend reader needs concrete context.

How the boundaries fit together

The diagram below shows the three runtime tiers — Browser SPA, Next.js BFF, Backend services — and the data crossings between them. The SPA never holds long-lived backend credentials and never reaches the backend directly; the BFF is the only process that does.

The Browser SPA is what the user clicks through. Every backend interaction goes through the BFF on the same origin (/api/arda/...), so the SPA never speaks to a backend service URL directly. In mock mode (NEXT_PUBLIC_MOCK_MODE=true), an MSW Service Worker inside the browser intercepts those same calls and returns fixture data without contacting the BFF — used for local development and end-to-end tests.

Sub-sections

Page	What it covers
Frontend Application Architecture	Technology stack, Next.js App Router conventions, BFF proxy mechanics, AuthContext / Redux split, and TypeScript conventions. Read this first for any new frontend work.
Data Flow and Caching	How item and kanban-card data crosses the boundary: REST envelopes, the SSRM grid datasource, the in-browser ItemCardsProvider cache, and the lifecycle of a single read (mount → cache → render).
Editing and Concurrency	Multi-user / multi-tab concerns: how the system detects that cached data has become stale, how it signals the user, and how it prevents acting on out-of-date selections.

What lives elsewhere

Concern	Section
Frontend design patterns and the curated catalogue of “use this pattern when…”	Architecture Patterns
Functional API reference (REST shapes the BFF proxies to)	Functional Reference
Domain entities the UI manipulates (Item, KanbanCard, Order, …)	Domain Model
End-user feature catalogue and use cases	Product Features, Product Use Cases
Frozen design decisions referenced from this section	Decisions Record