Back Office Client

1. Document Control

Property	Value
Package	@nx-app/client
Version	0.0.2-37
Type	Web Application (SPA)
Runtime	Browser / Bun (dev)
Deployment	Docker / Nginx

2. Scope & Objectives

2.1. Scope

The Back Office Client is the administrative interface for the BANA platform. It provides business owners, operators, and system administrators with comprehensive tools to manage their entire operation through a web browser.

2.2. Objectives

• Comprehensive Management: Full control over products, categories, merchants, employees, and reporting.
• Data Visualization: Rich charts and tables for business insights.
• Responsive Design: Functional on Desktop, Tablet, and Mobile browsers.
• Type Safety: End-to-end type safety with TypeScript and Zod validation.

3. Technology Stack

3.1. Core Framework

Technology	Version	Purpose
React	^19.2.1	UI Component Library
React DOM	^19.2.1	DOM Rendering
React Router	^7.9.4	Client-side Routing
TypeScript	~5.9.3	Type Safety

3.2. State Management

Technology	Version	Purpose
Redux Toolkit	^2.9.1	Global State Management
React Redux	^9.2.0	React-Redux Bindings
TanStack Query	^5.90.5	Server State & Caching
ra-core	^5.13.2	Admin Framework Core

3.3. UI Components

Technology	Version	Purpose
@nx-app/admin-ui-kit	workspace:*	Shared UI Component Library
Radix UI	Various	Accessible Primitives
Tailwind CSS	^4.1.16	Utility-first Styling
Lucide React	^0.552.0	Icon Library
next-themes	^0.4.6	Theme Switching

3.4. Forms & Validation

Technology	Version	Purpose
React Hook Form	^7.66.0	Form State Management
@hookform/resolvers	^5.2.2	Schema Validation Integration
Zod	^4.1.12	Runtime Schema Validation

3.5. Data Tables & Drag-and-Drop

Technology	Version	Purpose
TanStack Table	^8.21.3	Headless Data Tables
TanStack Virtual	^3.13.12	Virtualized Lists
@dnd-kit/core	^6.3.1	Drag-and-Drop Core
@dnd-kit/sortable	^10.0.0	Sortable Lists

3.6. Build & Development

Technology	Version	Purpose
Vite	^7.1.7	Build Tool & Dev Server
@vitejs/plugin-react	^5.0.4	React Integration
vite-plugin-pwa	^1.1.0	PWA Support
ESLint	^9.36.0	Code Linting
Prettier	3.6.2	Code Formatting

4. Architecture

4.1. Application Layers

Browser Request

→

React Router

→

Screen Component

→

API Service

→

Backend API

4.2. Context Providers

The application wraps components with multiple context providers for dependency injection and state management:

ApplicationContext
├── CoreApplicationContext (DI Container)
│   └── ReduxProvider (State Management)
│       └── ThemeProvider (Dark/Light Mode)
│           └── ActiveThemeProvider (Theme Customization)
│               └── App (Routes & Layout)

4.3. Core Admin Integration

The application uses ra-core (React Admin Core) with custom providers:

Provider	Implementation	Purpose
dataProvider	Custom REST Provider	API Communication
authProvider	AuthProvider class	Authentication Flow
i18nProvider	Custom Implementation	Internationalization

5. Project Structure

apps/client/
├── src/
│   ├── application/              # DI Container & Providers
│   │   ├── decorators/           # Custom Decorators
│   │   ├── providers/            # Auth & Data Providers
│   │   └── services/             # API Services
│   │       ├── apis/             # Domain-specific API Clients (25 files)
│   │       └── networks/         # Network Configuration
│   ├── components/               # Reusable UI Components
│   │   └── core/                 # Core Components
│   │       ├── breadcrumb/       # Navigation Breadcrumbs
│   │       ├── common/           # Shared Components
│   │       ├── input/            # Form Input Components
│   │       ├── notification/     # Toast Notifications
│   │       ├── table/            # Data Table Components
│   │       │   ├── base/         # Base Table Implementation
│   │       │   ├── data/         # Data Table Variants
│   │       │   └── view/         # View Table Variants
│   │       └── title/            # Page Titles
│   ├── constants/                # Application Constants
│   │   ├── screens/              # Screen-specific Constants
│   │   └── sub-screens/          # Sub-screen Constants
│   ├── helpers/                  # Utility Functions
│   ├── hooks/                    # Custom React Hooks
│   │   ├── api/                  # API Hooks
│   │   ├── table/                # Table Hooks
│   │   └── view/                 # View Hooks
│   ├── interfaces/               # TypeScript Interfaces (35 files)
│   │   └── product/              # Product-related Interfaces
│   ├── layout/                   # Layout Components
│   │   └── main/                 # Main Layout
│   ├── libs/                     # External Library Configs
│   │   └── tanstack/             # TanStack Query Config
│   ├── redux/                    # Redux Store
│   │   └── slices/               # Redux Slices (5 slices)
│   ├── screens/                  # Screen Components (23 modules)
│   └── themes/                   # Theme Configuration
├── scripts/                      # Build Scripts
└── public/                       # Static Assets

6. Screens & Routing

6.1. Screen Modules

The application contains 23 screen modules, each following a consistent structure:

Module	Path	Operations	Description
home	/	Dashboard	Main dashboard with statistics
product	/product	List, Create, Edit	Product management
category	/category	List, Create, Edit	Category management
category-template	/category-template	List, Create, Edit	Category templates
organizer	/organizer	List, Create, Edit	Organizer management
merchant	/merchant	List, Create, Edit	Merchant management
user	/user	List, Create, Edit	System user management
user-employee	/employee	List, Create, Edit	Employee management
customer	/customer	List, Create, Edit	Customer management
role	/role	List, Create, Edit	Role & permissions
device	/device	List, Create, Edit	POS device management
terminal	/terminal	List, Create, Edit	Payment terminal management
sale-channel	/sale-channel	List, Create, Edit	Sales channel configuration
order	/order	List, Show	Order viewing
transaction	/transaction	List, Show	Transaction history
invoice	/invoice	List	E-invoice management
report	/report/*	Revenue, Order	Business reports
settings	/settings/*	Profile, Password	User settings
sign-in	/login	Login	Authentication
sign-up	/sign-up	Register	User registration
errors	/401, /403, /404	Error Pages	HTTP error pages

6.2. Screen Structure Pattern

Each screen module follows a consistent folder structure:

screens/{module}/
├── index.ts                    # Module exports
├── list/
│   └── index.tsx               # List view component
├── create/
│   └── index.tsx               # Create form component
├── edit/
│   └── index.tsx               # Edit form component
├── show/
│   └── index.tsx               # Detail view component (optional)
├── form/
│   └── index.ts                # Shared form configuration
├── common/
│   └── index.ts                # Shared utilities
└── actions/
    └── index.ts                # Screen-specific actions

7. API Services

7.1. Service Architecture

All API services extend BaseApiService which provides standard CRUD operations:

export class BaseApiService extends BaseService {
  protected resource: string;

  constructor(opts: { scope: string; resource: string }) {
    super({ scope: opts.scope });
    this.resource = opts.resource;
  }
}

7.2. Available API Services

Service	Resource	Description
AuthApi	/auth	Authentication operations
OAuth2Api	/oauth2	OAuth2 integration
UserApi	/users	User management
UserConfigurationApi	/user-configurations	User preferences
EmployeeApi	/employees	Employee operations
OrganizerApi	/organizers	Organizer management
MerchantApi	/merchants	Merchant operations
MerchantTypeApi	/merchant-types	Merchant type definitions
ProductApi	/products	Product catalog
ProductVariantApi	/product-variants	Product variants
VariantApi	/variants	Variant definitions
CategoryApi	/categories	Category management
SaleChannelApi	/sale-channels	Sales channels
DeviceApi	/devices	POS devices
RoleApi	/roles	Role management
OrderApi	/orders	Order operations
TransactionApi	/transactions	Transaction history
InvoiceApi	/invoices	Invoice management
CustomerApi	/customers	Customer data
ReportApi	/reports	Business reports
BucketApi	/buckets	File storage
MetaLinkApi	/meta-links	Asset metadata
StaticAssetsApi	/static-assets	Static file serving

8. State Management

8.1. Redux Store Configuration

The Redux store is configured with multiple reducers and middleware:

const appReducer = combineReducers({
  route: routeReducer,
  temporary: temporaryReducer,
  common: commonReducer,
  product: productReducer,
  listView: listViewReducer,
});

8.2. Redux Slices

Slice	Purpose	Key State
route	Navigation state	Current route, history
temporary	Ephemeral data	Form drafts, unsaved changes
common	Shared application state	UI flags, global settings
product	Product editing state	Active tab, merchant context
listView	Table view preferences	Filters, sorting, pagination

8.3. Server State with TanStack Query

Server state (API data) is managed separately using TanStack Query:

Hook	Purpose	Usage
useGetData	Fetch single resource	Detail pages
useInfiniteGetData	Infinite scrolling	Long lists
useMutationData	Create/Update/Delete	Form submissions
useRefresh	Cache invalidation	After mutations
useVirtualAutocomplete	Virtualized search	Autocomplete fields

9. TypeScript Interfaces

9.1. Core Interfaces

The application defines 35+ interface files for type safety:

Interface File	Purpose
common.interface.ts	Shared utility types
redux.interface.ts	Redux action/state types
result.interface.ts	API response types
table.interface.ts	Table component types
sidebar.interface.ts	Navigation types

9.2. Domain Interfaces

Interface File	Domain
product.interface.ts	Product management
product/addon.interface.ts	Product addons
product/combo.interface.ts	Product combos
product/quota.interface.ts	Product quotas
product/product-variant.interface.ts	Product variants
product/product-feature.interface.ts	Product features
category.interface.ts	Category management
category-template.interface.ts	Category templates
merchant.interface.ts	Merchant data
merchant-type.interface.ts	Merchant types
organizer.interface.ts	Organizer data
user.interface.ts	User management
role.interface.ts	Role definitions
permission.interface.ts	Permission types
order.interface.ts	Order data
invoice.interface.ts	Invoice data
transaction.interface.ts	Transaction records
customer.interface.ts	Customer data
device.interface.ts	POS devices
terminal.interface.ts	Payment terminals
sale-channel.interface.ts	Sales channels
variant.interface.ts	Product variants
bucket.interface.ts	File storage
meta-link.interface.ts	Asset metadata

10. Custom Hooks

10.1. API Hooks

Located in src/hooks/api/:

Hook	Purpose
useGetData	Fetch data with caching
useInfiniteGetData	Paginated data fetching
useMutationData	Data mutations
useRefresh	Query cache refresh
useVirtualAutocomplete	Virtualized autocomplete
useVirtualAutocompleteArray	Multi-select autocomplete

10.2. Table Hooks

Located in src/hooks/table/:

Hook	Purpose
useDataTableController	Table instance management
useDataTableState	Table state synchronization

10.3. View Hooks

Located in src/hooks/view/:

Hook	Purpose
useViewConfig	View configuration
useViewState	View state management

10.4. Utility Hooks

Hook	File	Purpose
useDataProviderHeaders	useDataProviderHeaders.ts	API header injection
useWarnUnsavedChanges	useWarnUnsavedChanges.ts	Unsaved changes warning
useLogout	useLogout.ts	Logout handling

11. Authentication Flow

11.1. Auth Provider

The AuthProvider class extends DefaultAuthProvider and implements:

Method	Purpose
login()	Handle sign-in with credentials
logout()	Clear auth state and redirect
checkAuth()	Verify token validity
checkError()	Handle HTTP errors (401, 403)
getIdentity()	Retrieve current user
getPermissions()	Get user permissions
getRoles()	Get user roles

11.2. Authentication State

1. User submits credentials
2. AuthProvider.login() calls REST API
3. On success: save token, userId, username
4. Redirect to dashboard
5. checkAuth() validates on each protected route
6. 401/403 errors trigger logout

12. Theme System

12.1. Theme Provider Stack

ThemeProvider (next-themes)
└── ActiveThemeProvider (Custom)
    └── Tailwind CSS v4 (Dark mode via class)

12.2. Theme Features

• Dark/Light Mode: Toggle via next-themes
• System Preference: Respects OS preference
• Persistent: Stores preference in localStorage
• CSS Variables: Tailwind CSS custom properties

13. Build & Deployment

13.1. Build Scripts

Script	Command	Purpose
dev	vite --mode dev	Development server
build	sh ./scripts/build.sh	Production build
build:develop	sh ./scripts/rebuild.sh development	Development build
build:production	sh ./scripts/rebuild.sh production	Production build
preview	vite preview --port 4173	Preview production build
lint	sh ./scripts/lint.sh	Run ESLint

13.2. Docker Deployment

# Build Stage
FROM node:20-alpine AS builder
COPY . .
RUN bun install && bun run build

# Runtime Stage
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/nginx.conf

13.3. Environment Configuration

Environment variables are loaded via Vite's env system:

Variable	Purpose
VITE_NODE_ENV	Environment mode
VITE_API_BASE_URL	Backend API endpoint
VITE_AUTH_ENDPOINT	Authentication endpoint

14. Dependencies

14.1. Internal Dependencies

Package	Purpose
@nx-app/admin-ui-kit	Shared UI components
@nx-app/core	Shared utilities & locales

14.2. External Infrastructure

Package	Purpose
@minimaltech/ra-core-infra	React Admin infrastructure
@venizia/ignis-inversion	IoC Container
@loopback/filter	Query filter building

15. Code Statistics

Metric	Count
Source Files	~637
Screen Modules	23
API Services	25
TypeScript Interfaces	35+
Redux Slices	5
Custom Hooks	15+
React Components	100+