Back Office (Merchant Management)
1. Document Control
| Property | Value |
|---|---|
| Package | @nx-app/bo |
| Version | 0.0.1-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 | ~6.0.2 | 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:
typescript
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 modeTooltipProvider- 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
BO screens live under src/screens/ in two route tiers: root/organizer-level admin modules (auth/root/, 29 module directories) and a per-merchant workspace (auth/merchant/$merchant-id/). Each module typically exposes list / create / edit (or show) views. The module names below are the real source directory names; the path column reflects the route constant in src/constants/routes.ts.
5.1. Identity & Access
| Module | Path | Description |
|---|---|---|
organizer | /organizer | Organizer (parent entity) management |
merchant | /merchants | Merchant profile management |
user | /user | Platform user accounts |
merchant-user | /merchant-user | Merchant-scoped user accounts |
role | /role | Role management |
permission | /permission | Permission management |
policy-definition | /policy-definition | Casbin policy definitions |
5.2. Catalog & Configuration
| Module | Path | Description |
|---|---|---|
categories-product | /categories-product | Product category catalog |
category-template | /category-template | Reusable category templates |
unit-of-measure | /unit-of-measure | Units of measure |
tax-group | /tax-group | Tax group configuration |
settings | /settings | App-wide settings |
5.3. Subscription & Licensing
| Module | Path | Description |
|---|---|---|
subscription-plan | /subscription-plan | Subscription plan catalog |
license | /license | License records |
activation | /activation | License activation records |
onboarding | /onboarding | Merchant onboarding flow |
5.4. Outreach
| Module | Path | Description |
|---|---|---|
outreach-inquiry | /outreach-inquiry | Inbound outreach inquiries |
outreach-subscriber | /outreach-subscriber | Outreach subscribers |
5.5. Help Desk
| Module | Path | Description |
|---|---|---|
agent | /agent | Help desk agents |
agent-group | /agent-group | Agent groups |
assignment-rule | /assignment-rule | Ticket assignment rules |
sla-policy | /sla-policy | SLA policies |
hd-ticket-category | /hd-ticket-category | Ticket categories |
hd-ticket-tag | /hd-ticket-tag | Ticket tags |
5.6. Inventory & Devices
| Module | Path | Description |
|---|---|---|
vendors | /inventory-vendors | Supplier/vendor management |
locations | /inventory-locations | Inventory locations |
devices | /device | Device registration |
5.7. Home & Reports
| Module | Path | Description |
|---|---|---|
home | / | Dashboard home |
report | /report | Revenue and operations reports |
5.8. Merchant Workspace
Scoped under /merchant/:merchantId/ and hydrated from the selected merchant (auth/merchant/$merchant-id/):
| Module | Path | Description |
|---|---|---|
sale | /sale-order, /transaction, /sale-channel | Sale orders, transactions, sale channels |
finance | /finance-category, /finance-account, /finance-voucher | Finance categories, accounts, vouchers |
report | /ledger, /revenue/by-day, /revenue/by-product, /revenue/by-category | Ledger and revenue reports |
role | /role | Merchant-scoped roles |
setting-general | /general | Merchant general settings |
merchant | /merchant/:merchantId | Merchant detail (create / edit) |
5.9. Authentication
| Module | Path | Description |
|---|---|---|
sign-in | /sign-in | Login screen (no-auth/) |
6. Layout System
6.1. Main Layout
Authenticated layout with collapsible sidebar navigation (grouped by module), 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:
dockerfile
# 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 | 10 merchant-workspace modules (POS operations) + onboarding/organizer flows | 29 root/organizer admin modules + 6 merchant-workspace modules |
| 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