POS Terminal (Host Process)

1. Document Control

Property	Value
Package	`@nx-app/sale-main`
Crate Name	`BANA`
Type	Desktop Application (Host)
Version	0.1.0
Language	Rust (Edition 2021)
Framework	Tauri 2.x

2. Scope & Objectives

2.1. Scope

This package constitutes the Host Process of the POS application. Built using Tauri (Rust), it bridges the gap between the web-based UI (sale-renderer) and the physical hardware/operating system. It provides native capabilities that cannot be achieved with web technologies alone.

2.2. Objectives

Hardware Abstraction: Unified API for printers, USB devices, and payment terminals.
Security: Secure storage of authentication tokens in OS keychain.
Offline Persistence: Local SQLite database for offline operations.
Window Management: Multi-window support (Customer Display).
Cross-Platform: Support for Windows, macOS, Linux, Android, and iOS.

3. Technology Stack

3.1. Core Dependencies

Dependency	Version	Purpose
Tauri	2.x	Desktop application framework
SeaORM	2.0.0-rc	ORM for SQLite database
SQLx	0.8	Async SQL toolkit
Tokio	1.x	Async runtime
Serde	1.x	Serialization/Deserialization
Chrono	0.4	Date/time handling
UUID	1.0	Unique identifier generation

3.2. Tauri Plugins

Plugin	Version	Purpose
tauri-plugin-http	2.x	HTTP requests
tauri-plugin-fs	2.0.0	File system access
tauri-plugin-process	2.x	Process management
tauri-plugin-os	2.3.2	OS information
tauri-plugin-opener	2.x	Open URLs/files
tauri-plugin-log	2.7.1	Logging
tauri-plugin-localhost	2.3.1	Local HTTP server
tauri-plugin-machine-uid	0.1.3	Machine identification
tauri-plugin-updater	2.x	Auto-updates (Desktop)

3.3. Custom Tauri Plugins

Plugin	Path	Purpose
tauri-plugin-usb	`./tauri-plugin-usb`	USB device communication
tauri-plugin-payment	`./tauri-plugin-payment`	Payment terminal integration
tauri-plugin-external-display	`./tauri-plugin-external-display`	Customer display management

3.4. Development Tools

Tool	Version	Purpose
Specta	2.0.0-rc.22	TypeScript type generation
tauri-specta	2.0.0-rc.21	Tauri command type generation
dotenvy	0.15.7	Environment variables

4. Architecture

4.1. IPC Communication

React UI

→

Tauri IPC

→

Rust Commands

→

Hardware / OS

4.2. Application Context

The application manages a shared state through the AppContext structure:

rust

pub struct AppContext {
    pub datasource: Datasource,
    pub services: ServiceContainer,
    pub repositories: RepositoryContainer,
}

4.3. Module Structure

lib.rs
├── application/           # Application bootstrap
│   ├── application.rs     # Main application builder
│   ├── context.rs         # Shared state & DI containers
│   └── logger.rs          # Logging configuration
├── controllers/           # Command handlers
├── datasource/            # Database configuration
├── entities/              # SeaORM entities
├── helpers/               # Utility functions
├── pubs/                  # Public command modules
└── services/              # Business logic services

5. Project Structure

apps/sale-main/src-tauri/
├── src/
│   ├── main.rs                     # Application entry point
│   ├── lib.rs                      # Library root (modules)
│   ├── application/                # Application bootstrap
│   │   ├── mod.rs
│   │   ├── application.rs          # Tauri builder configuration
│   │   ├── context.rs              # AppState & containers
│   │   └── logger.rs               # Fern logger setup
│   ├── controllers/                # Command handlers
│   │   └── mod.rs
│   ├── datasource/                 # Database layer
│   │   ├── mod.rs
│   │   └── datasource.rs           # SQLite connection
│   ├── entities/                   # SeaORM entities
│   │   ├── mod.rs
│   │   ├── prelude.rs
│   │   └── user_configuration.rs
│   ├── helpers/                    # Utilities
│   │   ├── mod.rs
│   │   ├── error.rs                # Error handling
│   │   ├── network_request.rs      # HTTP helpers
│   │   ├── base_fetcher.rs         # Data fetching
│   │   └── request.rs              # Request utilities
│   ├── pubs/                       # Tauri commands (16 modules)
│   │   ├── mod.rs
│   │   ├── asset_pub.rs
│   │   ├── cart_pub.rs
│   │   ├── category_pub.rs
│   │   ├── common_pub.rs
│   │   ├── login_pub.rs
│   │   ├── merchant_pub.rs
│   │   ├── order_pub.rs
│   │   ├── organizer_pub.rs
│   │   ├── payment_attempt.rs
│   │   ├── payment_pub.rs
│   │   ├── permission_pub.rs
│   │   ├── product_pub.rs
│   │   ├── product_variant_pub.rs
│   │   ├── role_pub.rs
│   │   ├── sale_channel_pub.rs
│   │   └── user_pub.rs
│   └── services/                   # Business services (11 modules)
│       ├── mod.rs
│       ├── api_network_service.rs
│       ├── asset_service.rs
│       ├── auth_service.rs
│       ├── base_service.rs
│       ├── cart_service.rs
│       ├── cart_item_service.rs
│       ├── order_service.rs
│       ├── payment_service.rs
│       ├── payment_attempt_service.rs
│       ├── trail_services.rs
│       └── user_service.rs
├── common/                         # Shared utilities crate
│   ├── Cargo.toml
│   └── src/
│       ├── lib.rs
│       ├── constant.rs             # Application constants
│       ├── endpoint.rs             # API endpoints
│       ├── macros.rs               # Utility macros
│       └── traits.rs               # Shared traits
├── macros/                         # Procedural macros crate
│   ├── Cargo.toml
│   └── src/
│       ├── lib.rs
│       ├── controller.rs           # Controller macro
│       └── scoped_log.rs           # Logging macro
├── migration/                      # SeaORM migrations
│   ├── Cargo.toml
│   └── src/
│       ├── lib.rs
│       ├── main.rs
│       └── m20251222_050923_create_tables.rs
├── tauri-plugin-usb/               # USB device plugin
│   ├── Cargo.toml
│   └── src/
│       ├── lib.rs
│       ├── commands.rs
│       ├── desktop.rs
│       ├── mobile.rs
│       ├── error.rs
│       └── models.rs
├── tauri-plugin-payment/           # Payment terminal plugin
│   ├── Cargo.toml
│   └── src/
│       ├── lib.rs
│       ├── commands.rs
│       ├── desktop.rs
│       ├── mobile.rs
│       ├── error.rs
│       └── models.rs
├── tauri-plugin-external-display/  # Customer display plugin
│   ├── Cargo.toml
│   └── src/
│       ├── lib.rs
│       ├── commands.rs
│       ├── desktop.rs
│       ├── mobile.rs
│       ├── error.rs
│       └── models.rs
├── Cargo.toml                      # Workspace manifest
├── tauri.conf.json                 # Tauri configuration
└── build.rs                        # Build script

6. Tauri Commands

6.1. CRUD Commands

Generated automatically for common operations via macros:

Resource	Operations
merchant	find, find_one, create, update, delete
category	find, find_one, create, update, delete
product	find, find_one, create, update, delete
product_variant	find, find_one, create, update, delete
organizer	find, find_one, create, update, delete
sale_channel	find, find_one, create, update, delete
cart	find, find_one, create, update, delete
cart_item	find, find_one, create, update, delete

6.2. Custom Commands

Command	Module	Description
`asset_controller_i18n_file`	asset_pub	Load i18n translations
`asset_controller_vnpay_qr_frame_image`	asset_pub	Get VNPay QR frame
`auth_controller_sign_in`	login_pub	User authentication
`auth_controller_sign_out`	login_pub	User logout
`auth_controller_who_am_i`	login_pub	Get current user
`auth_controller_auth_token`	login_pub	Get auth token
`user_controller_get_user_profile`	user_pub	Get user profile
`cart_controller_cart_items`	cart_pub	Get cart items
`cart_controller_add_item`	cart_pub	Add item to cart
`cart_controller_clear_cart`	cart_pub	Clear cart
`cart_item_controller_update_quantity`	cart_pub	Update item quantity
`order_controller_checkout`	order_pub	Create order from cart
`order_controller_revert_checkout`	order_pub	Cancel checkout
`payment_controller_checkout`	payment_pub	Process payment
`payment_controller_cancel`	payment_pub	Cancel payment
`payment_controller_system_ipn`	payment_pub	Handle payment IPN
`payment_attempt_controller_find_by_id`	payment_attempt	Find payment attempt

7. Custom Plugins

7.1. USB Plugin (`tauri-plugin-usb`)

Provides USB device communication for thermal printers and other peripherals.

Command	Description
`get_devices`	List connected USB devices
`connect`	Connect to USB device
`send`	Send data to device
`disconnect`	Disconnect from device
`get_connected_device`	Get current device

Platform Support:

Desktop: Direct USB communication
Mobile: Platform-specific implementation

7.2. Payment Plugin (`tauri-plugin-payment`)

Handles payment terminal integration.

Command	Description
`open_payment`	Open payment interface

Platform Support:

Desktop: Not implemented (uses web API)
Mobile (Android): Native payment SDK integration

7.3. External Display Plugin (`tauri-plugin-external-display`)

Manages customer-facing displays (secondary screens).

Command	Description
`send_data`	Send data to customer display

Features:

Opens secondary window on external display
Supports VFD and LCD displays
Real-time cart updates

8. Services Layer

8.1. Service Architecture

Services encapsulate business logic and interact with external APIs:

Service	Purpose
ApiNetworkService	HTTP client for backend API
AuthService	Authentication & token management
UserService	User profile operations
AssetService	Asset/file management
CartService	Shopping cart logic
CartItemService	Cart item management
OrderService	Order creation & management
PaymentService	Payment processing
PaymentAttemptService	Payment attempt tracking
TrailServices	Audit trail logging

8.2. Base Service Pattern

All services extend a base implementation:

rust

pub trait BaseService {
    fn new() -> Self;
    // Common service methods
}

9. Database Layer

9.1. Datasource Configuration

SQLite database with SeaORM for async operations:

rust

pub struct Datasource {
    pub connection: DatabaseConnection,
}

pub struct DatasourceConnectionOptions {
    pub path: String,
}

9.2. Database Location

Environment	Path
Debug	`app_data/db/{app_name}.sqlite`
Release	OS app data directory

9.3. Migrations

Database migrations are managed via SeaORM Migration:

rust

Migrator::up(&datasource.connection, None).await?;

10. Application Lifecycle

10.1. Bootstrap Flow

1. Application::new()
   └── Get base directory
2. Application::build()
   ├── Create Tauri Builder
   ├── Manage options & base_dir
   ├── bind_plugins() - Attach all plugins
   ├── bind_commands() - Register IPC commands
   └── setup() - Async initialization
       ├── configure() - Setup datasource & state
       │   ├── Configure SQLite database
       │   ├── Create ServiceContainer
       │   ├── Create RepositoryContainer
       │   └── Manage AppState
       ├── Emit "init_ready" event
       └── migrate() - Run database migrations
           └── Emit "migration_error" on failure
3. builder.run() - Start Tauri runtime

10.2. Events

Event	Payload	Description
`init_ready`	`true`	Application initialized successfully
`init_error`	String	Initialization failed
`migration_error`	String	Database migration failed

11. Workspace Structure

11.1. Workspace Members

toml

[workspace]
members = [
  ".",                              # Main application
  "macros",                         # Procedural macros
  "migration",                      # Database migrations
  "tauri-plugin-external-display",  # Customer display plugin
  "tauri-plugin-usb",               # USB communication plugin
  "tauri-plugin-payment"            # Payment integration plugin
]

11.2. Internal Crates

Crate	Purpose
`common`	Shared constants, traits, and macros
`macros`	Procedural macros (scoped_log, controller)
`migration`	SeaORM database migrations

12. Platform-Specific Features

12.1. Desktop Only

rust

#[cfg(desktop)]
// Features only available on desktop platforms
- tauri-plugin-updater    // Auto-updates
- printers crate          // ESC/POS printer support

12.2. Mobile Only (Android)

rust

#[cfg(mobile)]
// Features only available on mobile platforms
- tauri-plugin-payment    // Native payment SDK

13. Build Configuration

13.1. Release Profile

Optimized for minimal binary size:

toml

[profile.release]
opt-level = "z"      # Maximum size optimization
lto = true           # Link Time Optimization
codegen-units = 1    # Better compression
panic = "abort"      # Remove unwinding code
strip = true         # Strip debug symbols

13.2. Build Artifacts

Platform	Artifacts
Windows	`.msi`, `.exe`
macOS	`.dmg`, `.app`
Linux	`.deb`, `.AppImage`
Android	`.apk`, `.aab`

14. Development

14.1. Prerequisites

Requirement	Purpose
Rust	Latest stable toolchain
Tauri CLI	Build and development
libwebkit2gtk-4.0-dev	Linux WebView
build-essential	Linux compilation
Xcode CLI Tools	macOS compilation

14.2. Environment Variables

Variable	Purpose
`APP_ENV_APPLICATION_NAME`	Database name prefix
`EXTERNAL_PORT`	Local HTTP server port

15. Code Statistics

Metric	Count
Rust Source Files	~75
Tauri Commands	50+
Custom Plugins	3
Services	11
Database Entities	1+
Workspace Crates	7

Client Guide

Providers

Invoice Types

POS Terminal (Host Process) ​

1. Document Control ​

2. Scope & Objectives ​

2.1. Scope ​

2.2. Objectives ​

3. Technology Stack ​

3.1. Core Dependencies ​

3.2. Tauri Plugins ​

3.3. Custom Tauri Plugins ​

3.4. Development Tools ​

4. Architecture ​

4.1. IPC Communication ​

4.2. Application Context ​

4.3. Module Structure ​

5. Project Structure ​

6. Tauri Commands ​

6.1. CRUD Commands ​

6.2. Custom Commands ​

7. Custom Plugins ​

7.1. USB Plugin (tauri-plugin-usb) ​

7.2. Payment Plugin (tauri-plugin-payment) ​

7.3. External Display Plugin (tauri-plugin-external-display) ​

8. Services Layer ​

8.1. Service Architecture ​

8.2. Base Service Pattern ​

9. Database Layer ​

9.1. Datasource Configuration ​

9.2. Database Location ​

9.3. Migrations ​

10. Application Lifecycle ​

10.1. Bootstrap Flow ​

10.2. Events ​

11. Workspace Structure ​

11.1. Workspace Members ​

11.2. Internal Crates ​

12. Platform-Specific Features ​

12.1. Desktop Only ​

12.2. Mobile Only (Android) ​

13. Build Configuration ​

13.1. Release Profile ​

13.2. Build Artifacts ​

14. Development ​

14.1. Prerequisites ​

14.2. Environment Variables ​

15. Code Statistics ​

POS Terminal (Host Process)

1. Document Control

2. Scope & Objectives

2.1. Scope

2.2. Objectives

3. Technology Stack

3.1. Core Dependencies

3.2. Tauri Plugins

3.3. Custom Tauri Plugins

3.4. Development Tools

4. Architecture

4.1. IPC Communication

4.2. Application Context

4.3. Module Structure

5. Project Structure

6. Tauri Commands

6.1. CRUD Commands

6.2. Custom Commands

7. Custom Plugins

7.1. USB Plugin (`tauri-plugin-usb`)

7.2. Payment Plugin (`tauri-plugin-payment`)

7.3. External Display Plugin (`tauri-plugin-external-display`)

8. Services Layer

8.1. Service Architecture

8.2. Base Service Pattern

9. Database Layer

9.1. Datasource Configuration

9.2. Database Location

9.3. Migrations

10. Application Lifecycle

10.1. Bootstrap Flow

10.2. Events

11. Workspace Structure

11.1. Workspace Members

11.2. Internal Crates

12. Platform-Specific Features

12.1. Desktop Only

12.2. Mobile Only (Android)

13. Build Configuration

13.1. Release Profile

13.2. Build Artifacts

14. Development

14.1. Prerequisites

14.2. Environment Variables

15. Code Statistics