Client Ecosystem Overview

1. Document Control

Property	Value
Status	Active
Version	1.0.0
Last Updated	2025-01-20
Maintainer	Frontend Team

2. Scope & Objectives

2.1. Scope

The Client Ecosystem encompasses all user-facing applications in the BANA solution, including the Point-of-Sale (POS) terminal, the Back Office management dashboard, and the shared libraries that support them.

2.2. Strategic Objectives

Objective	Description	Metric
Consistency	Maintain unified UX/UI across platforms using shared design system	Single component library
Performance	Sub-100ms response times for critical POS interactions	Cart operations < 100ms
Maintainability	Maximize code reuse via shared core libraries	80%+ shared utilities
Offline Resilience	Core POS functionality without internet (Local-First)	100% offline cart operations

3. Application Portfolio

3.1. Applications Overview

📱

Applications

User-facing deliverables

🌐

client

Back Office Web App

🖥️

sale-main

Tauri Backend (Rust)

🎨

sale-renderer

POS UI (React)

▼ Imports

📦

Shared Libraries

Internal packages

🧩

admin-ui-kit

36 UI Components

🔧

core

Utilities & Locales

3.2. Application Details

Application	Package	Type	Files	Port	Primary User
Back Office	`@nx-app/client`	Web SPA	637 TS/TSX	3001	Managers / Owners
POS Terminal	`@nx-app/sale-main`	Desktop (Rust)	46 Rust	N/A	Cashiers
POS UI	`@nx-app/sale-renderer`	Web SPA (Tauri)	337 TS/TSX	3002	Cashiers
UI Kit	`@nx-app/admin-ui-kit`	Library	44 TS/TSX	N/A	Developers
Core	`@nx-app/core`	Library	11 TS	N/A	Developers

3.3. Deliverables

Application	Deployment	Artifact
Back Office	Docker / Nginx	Static bundle (`dist/`)
POS Terminal	Native Installer	`.msi` (Win), `.dmg` (Mac), `.deb` (Linux)
POS UI	Embedded in Tauri	Static bundle (WebView)

4. Technology Stack

4.1. Core Technologies

Layer	Technology	Version	Purpose
Runtime	Bun	1.3.2+	JavaScript/TypeScript runtime
Framework	React	19.2.x	UI framework
Build Tool	Vite	7.x	Development & bundling
Styling	Tailwind CSS	4.1.x	Utility-first CSS
Desktop	Tauri	2.9.1	Native desktop framework
Backend (Tauri)	Rust	Stable	POS native layer

4.2. State Management

Scope	Library	Version	Use Case
Server State	TanStack Query	5.90.5	API data fetching & caching
Global UI State	Redux Toolkit	2.9.x	Cart, user preferences, navigation
Form State	React Hook Form	7.66.0	Form validation with Zod
Admin Framework	react-admin	5.13.x	CRUD operations, data provider

4.3. UI Components

Library	Version	Purpose
Radix UI	Latest	Accessible primitives
shadcn/ui	Latest	Pre-built components
Lucide Icons	0.562.0	Icon library
TanStack Table	8.21.3	Data tables
TanStack Virtual	Latest	Virtualized lists
Recharts	2.15.4	Charts (sale-renderer)

4.4. Tauri-Specific (sale-main)

Library	Purpose
sea-orm	SQLite ORM
reqwest	HTTP client
tokio	Async runtime
serde	JSON serialization
tracing	Structured logging

5. Folder Structure

5.1. Common Application Structure

apps/{app-name}/
├── src/
│   ├── application/          # DI container, providers, API services
│   ├── components/           # React components
│   │   ├── core/             # Custom components
│   │   └── shadcn/           # shadcn UI components
│   ├── constants/            # Routes, endpoints, configurations
│   ├── helpers/              # Utility functions
│   ├── hooks/                # Custom React hooks
│   ├── interfaces/           # TypeScript interfaces
│   ├── layout/               # Layout components
│   ├── libs/                 # Library configurations
│   ├── redux/                # State management
│   ├── screens/              # Page components
│   ├── App.tsx               # Root component
│   ├── main.tsx              # Entry point
│   └── index.css             # Global styles
├── public/                   # Static assets
├── index.html                # HTML entry
├── package.json
├── tsconfig.json
├── vite.config.ts
└── tailwind.config.ts

5.2. Application-Specific Structure

Back Office (client)

src/
├── screens/                  # 23 screen modules
│   ├── product/              # Product management
│   ├── category/             # Category management
│   ├── merchant/             # Merchant management
│   ├── organizer/            # Organization management
│   ├── customer/             # Customer management
│   ├── user/                 # User management
│   ├── employee/             # Employee management
│   ├── role/                 # Role management
│   ├── device/               # Device management
│   ├── sale-channel/         # Sales channel config
│   ├── terminal/             # Terminal management
│   ├── order/                # Order management
│   ├── invoice/              # Invoice management
│   ├── transaction/          # Transaction history
│   ├── report/               # Reporting dashboards
│   │   ├── revenue/
│   │   └── orders/
│   ├── settings/             # System settings
│   ├── sign-in/
│   ├── sign-up/
│   └── home/                 # Dashboard
├── application/
│   └── services/             # 20+ API services
└── redux/
    └── slices/               # 5 Redux slices
        ├── route/
        ├── temporary/
        ├── common/
        ├── product/
        └── listView/

POS UI (sale-renderer)

src/
├── screens/                  # 8 screen modules
│   ├── sale/                 # Main POS screen
│   ├── home/                 # Dashboard
│   ├── settings/             # Settings
│   ├── customer/             # Customer display
│   ├── errors/               # Error pages
│   ├── sign-in/
│   └── term-of-use/
├── hooks/
│   └── screens/
│       └── sale/             # Sale-specific hooks
│           ├── useCart.ts
│           ├── useProductVariant.ts
│           └── usePayment.ts
├── socket/                   # WebSocket integration
│   ├── connection-manager.ts
│   └── subscription-manager.ts
└── redux/
    └── slices/               # 8 Redux slices
        ├── cart/             # Shopping cart
        ├── order/            # Order state
        ├── payment/          # Payment processing
        ├── product/          # Product catalog
        ├── sale/             # Sale operations
        ├── userProfile/
        ├── common/
        └── temporary/

Tauri Backend (sale-main)

src-tauri/
├── src/
│   ├── application/          # App initialization
│   │   ├── application.rs
│   │   ├── context.rs
│   │   └── logger.rs
│   ├── pubs/                 # IPC commands (17 modules)
│   │   ├── login_pub.rs
│   │   ├── user_pub.rs
│   │   ├── merchant_pub.rs
│   │   ├── product_pub.rs
│   │   ├── category_pub.rs
│   │   ├── cart_pub.rs
│   │   ├── order_pub.rs
│   │   ├── payment_pub.rs
│   │   ├── payment_attempt.rs
│   │   ├── asset_pub.rs
│   │   ├── role_pub.rs
│   │   ├── permission_pub.rs
│   │   ├── sale_channel_pub.rs
│   │   ├── organizer_pub.rs
│   │   └── product_variant_pub.rs
│   ├── services/             # Business logic (12 modules)
│   │   ├── auth_service.rs
│   │   ├── user_service.rs
│   │   ├── cart_service.rs
│   │   ├── cart_item_service.rs
│   │   ├── order_service.rs
│   │   ├── payment_service.rs
│   │   ├── api_network_service.rs
│   │   └── base_service.rs
│   ├── datasource/           # SQLite database
│   ├── entities/             # Database schemas
│   ├── helpers/              # Utilities
│   ├── main.rs
│   └── lib.rs
├── migration/                # DB migrations
├── capabilities/             # Tauri permissions
└── tauri.conf.json           # Tauri config

6. API Services

6.1. Back Office Services (20+)

Service	Purpose	Key Methods
AuthApi	Authentication	signIn, signOut, refresh
OAuth2Api	OAuth integration	authorize, callback
UserApi	User management	CRUD, profile
EmployeeApi	Employee management	CRUD, assign roles
RoleApi	Role management	CRUD, permissions
ProductApi	Product catalog	CRUD, aggregate
CategoryApi	Categories	CRUD, tree
VariantApi	Product variants	CRUD
MerchantApi	Merchants	CRUD
OrganizerApi	Organizations	CRUD
OrderApi	Orders	CRUD, status
InvoiceApi	Invoices	CRUD, generate
TransactionApi	Transactions	list, details
DeviceApi	Devices	CRUD, activate
SaleChannelApi	Sales channels	CRUD, assign
BucketApi	File storage	upload, download
MetaLinkApi	Metadata links	CRUD
UserConfigurationApi	User settings	CRUD
StaticAssetsApi	Static files	serve
ReportApi	Reports	revenue, orders

6.2. POS Services (15)

Service	Purpose
AuthApi	Authentication
UserApi	User profile
AssetApi	File access
MerchantApi	Merchant data
OrganizerApi	Organization data
SaleChannelApi	Sales channels
CategoryApi	Categories
ProductApi	Product catalog
ProductVariantApi	Variants
CartApi	Cart management
CartItemApi	Cart items
OrderApi	Order creation
PaymentApi	Payment processing
PaymentAttemptApi	Payment attempts

7. State Management

7.1. Redux Slices

Back Office

Slice	State	Actions
route	Current route, history	navigate, goBack
temporary	Modals, loading states	setModal, setLoading
common	Global app state	setLanguage, setTheme
product	Product editing state	setProduct, clearProduct
listView	Table configurations	setFilters, setSort

POS

Slice	State	Actions
cart	Cart items, totals	addItem, removeItem, clearCart
order	Current order	createOrder, updateStatus
payment	Payment state	initiatePayment, confirmPayment
product	Product catalog	loadProducts, searchProducts
sale	Sale session	openSession, closeSession
userProfile	Current user	setUser, clearUser
common	Global state	setMerchant, setSaleChannel
temporary	UI state	setLoading, setModal

7.2. State Flow

8. Routing Configuration

8.1. Back Office Routes

Path	Screen	Auth Required
`/`	Home (Dashboard)	Yes
`/product/*`	Product management	Yes
`/category/*`	Category management	Yes
`/merchant/*`	Merchant management	Yes
`/organizer/*`	Organization management	Yes
`/customer/*`	Customer management	Yes
`/user/*`	User management	Yes
`/employee/*`	Employee management	Yes
`/role/*`	Role management	Yes
`/device/*`	Device management	Yes
`/order/*`	Order management	Yes
`/invoice/*`	Invoice management	Yes
`/transaction/*`	Transaction history	Yes
`/report/*`	Reports	Yes
`/settings/*`	Settings	Yes
`/sign-in`	Login	No
`/sign-up`	Registration	No

8.2. POS Routes

Path	Screen	Auth Required
`/sale`	Main POS	Yes
`/settings`	General settings	Yes
`/account-setting`	Account settings	Yes
`/store-setting`	Store settings	Yes
`/customer`	Customer display	No
`/term-of-use`	Terms of use	No
`/error/*`	Error pages	No

9. Real-Time Communication

9.1. WebSocket (POS)

🔌

Socket.IO Integration

Real-time event handling

📡SocketConnectionManager→Connection lifecycle

📬SocketSubscriptionManager→Event subscriptions

📦OrderSocketService→Order event handling

9.2. Event Types

Event	Source	Description
`order:created`	Server	New order created
`order:updated`	Server	Order status changed
`payment:confirmed`	Payment Gateway	Payment successful
`payment:failed`	Payment Gateway	Payment failed

10. Tauri IPC Communication

10.1. Command Pattern

10.2. IPC Commands (17 modules)

Module	Commands
login_pub	sign_in, sign_out, verify_token
user_pub	get_user, update_user
merchant_pub	list_merchants, get_merchant
product_pub	list_products, get_product, search
category_pub	list_categories, get_tree
cart_pub	get_cart, create_cart, clear_cart
order_pub	create_order, get_order, list_orders
payment_pub	initiate_payment, confirm_payment
asset_pub	upload_file, get_file

10.3. Data Persistence

Store	Technology	Purpose
Local DB	SQLite + SeaORM	Offline data
Cache	In-memory	Session data
Keychain	OS Secure Storage	Auth tokens

11. Build & Deployment

11.1. Build Configuration

App	Build Tool	Output	Command
client	Vite 7	`dist/`	`bun run build`
sale-renderer	Vite 7	`dist/`	`bun run build`
sale-main	Cargo/Tauri	Native binary	`bun run tauri build`
admin-ui-kit	tsc	`dist/`	`bun run build`

11.2. Vite Optimizations

typescript

// Common Vite configuration
{
  build: {
    minify: 'terser',
    rollupOptions: {
      output: {
        manualChunks: {
          react: ['react', 'react-dom'],
          admin: ['react-admin', 'ra-core'],
          infra: ['@minimaltech/ra-core-infra'],
          lodash: ['lodash'],
        }
      }
    }
  }
}

11.3. Deployment Topology

12. Code Quality

12.1. Linting & Formatting

Tool	Config	Purpose
ESLint	Strict React rules	Code quality
Prettier	Pre-commit hooks	Code formatting
TypeScript	Strict mode	Type safety

12.2. Type Safety Requirements

TypeScript "strict" mode enabled
No explicit any types allowed
All API responses typed with Zod schemas
Generated types for API contracts

13. Next Steps

Back Office (client) - Detailed web admin documentation
POS Terminal (sale-main) - Tauri backend documentation
POS UI (sale-renderer) - POS frontend documentation
Admin UI Kit - Component library documentation

Client Guide

Providers

Invoice Types

Client Ecosystem Overview ​

1. Document Control ​

2. Scope & Objectives ​

2.1. Scope ​

2.2. Strategic Objectives ​

3. Application Portfolio ​

3.1. Applications Overview ​

3.2. Application Details ​

3.3. Deliverables ​

4. Technology Stack ​

4.1. Core Technologies ​

4.2. State Management ​

4.3. UI Components ​

4.4. Tauri-Specific (sale-main) ​

5. Folder Structure ​

5.1. Common Application Structure ​

5.2. Application-Specific Structure ​

Back Office (client) ​

POS UI (sale-renderer) ​

Tauri Backend (sale-main) ​

6. API Services ​

6.1. Back Office Services (20+) ​

6.2. POS Services (15) ​

7. State Management ​

7.1. Redux Slices ​

Back Office ​

POS ​

7.2. State Flow ​

8. Routing Configuration ​

8.1. Back Office Routes ​

8.2. POS Routes ​

9. Real-Time Communication ​

9.1. WebSocket (POS) ​

9.2. Event Types ​

10. Tauri IPC Communication ​

10.1. Command Pattern ​

10.2. IPC Commands (17 modules) ​

10.3. Data Persistence ​

11. Build & Deployment ​

11.1. Build Configuration ​

11.2. Vite Optimizations ​

11.3. Deployment Topology ​

12. Code Quality ​

12.1. Linting & Formatting ​

12.2. Type Safety Requirements ​

13. Next Steps ​