Back Office (Merchant Management)

1. Document Control

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

2. Scope & Objectives

2.1. Scope

The Back Office (bo) is the merchant management interface for the BANA platform. It provides business owners, operators, and system administrators with tools to manage merchants, products, categories, inventory, invoices, finances, and employee operations through a web browser.

2.2. Objectives

• Merchant Management: Full lifecycle management of merchants, organizers, and vendor relationships.
• Comprehensive Operations: Products, categories, inventory, purchase orders, sale orders, invoices, and finance management.
• Role-Based Access: Permission-controlled screens for different user roles.
• Data Visualization: Reports for revenue, orders, and product performance.
• Responsive Design: Desktop, tablet, and mobile browser support.

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
Vite	^7.1.7	Build Tool & Dev Server

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
TanStack Table	^8.21.3	Data Table Management
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	^1.4.3	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 Bridge
react-phone-number-input	^3.4.14	Phone Input
react-number-format	^5.4.4	Numeric Formatting
react-day-picker	^9.13.2	Date Picker

3.5. Utilities

Technology	Version	Purpose
@dnd-kit	Various	Drag-and-Drop (sortable)
xlsx	^0.18.5	Excel Import/Export
papaparse	^5.5.3	CSV Parsing
compressorjs	^1.2.1	Image Compression
dayjs	^1.11.18	Date Formatting
sonner	^2.0.7	Toast Notifications

4. Architecture

4.1. Application Bootstrap

The BO app extends AdminUiKitApplication via RaApplication:

class RaApplication extends AdminUiKitApplication {
  // Initializes 18+ API services:
  // Auth, Merchant, Product, Category, User, Employee,
  // SaleChannel, SaleOrder, Invoice, Inventory, Finance,
  // Payment, Transaction, Role, Device, Report, etc.
}

ApplicationContext wraps the app with:

• CoreApplicationContext — Admin framework context
• Redux Provider — Global state
• ThemeProvider — Dark/light mode
• TooltipProvider — Global tooltips

4.2. Configuration

Config	Source	Default
API Base URL	VITE_BASE_URL	http://localhost:3000/api
OAuth URL	VITE_NX_OAUTH_BASE_URL	—
App Name	package.json	@nx-app/bo

4.3. Data Layer

• DefaultRestDataProvider for all API communication
• DefaultAuthService for JWT authentication
• TanStack Query for server state caching and invalidation
• Redux for UI state (sidebar, filters, preferences)

5. Screen Modules

The BO app contains 29 screen modules, each providing list/create/read/update/delete views:

5.1. Core Business

Module	Path	Description
merchant	/merchants	Merchant profile management
organizer	/organizers	Organizer (parent entity) management
vendor	/vendors	Supplier/vendor management
settings	/settings	App-wide settings

5.2. Catalog

Module	Path	Description
product	/products	Product CRUD and catalog
category	/categories	Category hierarchy
category-template	/category-templates	Reusable category templates
sale-channel	/sale-channels	Multi-channel configuration

5.3. Sales & Orders

Module	Path	Description
sale-order	/sale-orders	Sale order management
purchase-order	/purchase-orders	Purchase order lifecycle
invoice	/invoices	Invoice generation and tracking
transaction	/transactions	Payment transaction records

5.4. Inventory & Stock

Module	Path	Description
inventory	/inventory	Inventory management
inventory-tracking	/inventory-tracking	Stock movement tracking
importation	/importations	Stock import operations

5.5. Finance

Module	Path	Description
finance	/finance	Financial transactions, categories, wallets

5.6. People

Module	Path	Description
customer	/customers	Customer database
user	/users	User accounts
user-employee	/employees	Employee management
role	/roles	Role & permission management

5.7. Hardware & Reports

Module	Path	Description
terminal	/terminals	POS terminal management
devices	/devices	Device registration
report	/reports	Revenue, order, and product reports

5.8. Authentication

Module	Path	Description
sign-in	/sign-in	Login screen
sign-up	/sign-up	Registration screen
home	/	Dashboard home

6. Layout System

6.1. Main Layout

Authenticated layout with collapsible sidebar navigation (29 menu items), header with user profile, and content area.

6.2. Form Layout

BaseFormLayout provides standardized form pages with:

• Filter bar — TextField, Status dropdown filters
• Action buttons — Save, Cancel, custom actions
• RouteContextProvider — Screen-level routing context

6.3. No-Auth Layout

Minimal layout for sign-in/sign-up screens without sidebar navigation.

7. Custom Hooks

7.1. API Hooks

Hook	Purpose
useGetData	Fetch data with TanStack Query
useInfiniteGetData	Infinite scroll data fetching
useMutationData	Create/Update/Delete mutations
useRefresh	Force data refresh
useVirtualAutocomplete	Virtualized autocomplete (single)
useVirtualAutocompleteArray	Virtualized autocomplete (multi)

7.2. State Hooks

Hook	Purpose
useAppDispatch	Typed Redux dispatch
useAppSelector	Typed Redux selector
useUserPreferences	User settings persistence
useUserProfile	Current user profile data
useLogout	Logout flow
useWarnUnsavedChanges	Unsaved changes warning

7.3. Table Hooks

Hook	Purpose
useDataTableController	Table state + data fetching
useDataTableState	Table column/filter state
useBaseTableAutosave	Auto-save inline edits

8. Build & Deployment

8.1. Vite Configuration

• Code splitting: Manual chunk for infra bundle
• Chunk size warning: 600KB limit
• PWA: Auto-update strategy, no manifest
• Dev server: Port 3000, strict port, HMR enabled

8.2. Docker Build

Multi-stage build:

# Stage 1: Dependencies (bun:1-alpine)
# Stage 2: Build (bun run build:production)
# Stage 3: Production (nginx:1.27-alpine)

8.3. Nginx Configuration

Feature	Setting
Compression	Gzip enabled (text, JS, CSS, JSON, SVG)
Security Headers	X-Frame-Options, X-Content-Type-Options, X-XSS-Protection
Asset Caching	1 year (immutable)
Service Worker	1 hour cache
SPA Routing	Catch-all redirect to index.html
Hidden Files	Denied (except .well-known)

8.4. 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	ESLint + Prettier

9. Differences from Client App

Aspect	Client (@nx-app/client)	BO (@nx-app/bo)
Purpose	Admin dashboard (all platform management)	Merchant-focused management
Scope	Full platform administration	Merchant operations
Modules	29 screens	29 screens (merchant-oriented)
Additional Tools	—	Excel import/export, CSV parsing, image compression, drag-and-drop

10. Related Documentation

• Client App — Back Office Client
• Admin UI Kit — Shared component library
• Identity Service — User & authentication
• Commerce Service — Product catalog