POS System Overview
Relevant source files
The following files were used as context for generating this wiki page:
The DRX Point of Sale (POS) system is a privacy-first, mobile-optimized transaction processing module designed for retail businesses with high inventory sensitivity. It supports offline sales, weight-based (fractional) transactions, and integrated customer credit management. The system is built on a local-first data architecture that ensures business continuity without a constant internet connection, with automatic synchronization to the cloud when connectivity is restored.
Sources: README.md:3-8, scripts/help-center-data.ts:25-35, testsprite_tests/standard_prd.json:6-14
Core Transaction Logic
The POS facilitates sales through a structured workflow involving product discovery, cart management, and multi-method checkout. It specifically supports weight-based sales (grams) and unit-based sales (count), applying deterministic pricing rules and tax calculations.
Transaction Workflow
- Product Discovery: Staff find items via barcode scanning, text search (name/SKU), "Quickpicks" (pre-set quantities), or "Favorites".
- Cart Management: Items are added to a cart where quantities can be adjusted. Support for fractional weights allows precise inventory tracking for products like cannabis or bulk solids.
- Checkout: Staff can assign a customer profile or proceed as a guest. Payment methods include Cash, Card, and Credit (Charge to Account).
Sources: app/(app)/help/page.tsx:75-90, scripts/help-center-data.ts:133-145, db/migrations/20250228000001_pos_weight_shrinkage_loyalty_consolidated.json:step_28
Order Processing Sequence
The following diagram illustrates the sequence of events during a weight-based checkout process:
Inventory & Pricing Integration
The POS system is deeply integrated with the inventory module to ensure real-time accuracy and financial traceability.
Weight-Based Sales and Aliases
Products are categorized by measurement type:
- Liquids: Measured in ounces (oz).
- Solids: Measured in grams (g).
- Unit Aliases: Staff use "Nicknames" (e.g., "OG8" for 3.5g) to trigger specific quantity and unit combinations instantly.
Sources: README.md:126-130, scripts/help-center-data.ts:413-425, db/migrations/20250228000001_pos_weight_shrinkage_loyalty_consolidated.json:step_4
Bulk Pricing Rules
The system automatically applies bulk pricing based on the weight thresholds defined for a product.
| Field | Type | Description |
|---|---|---|
min_weight_grams | Decimal | Minimum weight required to trigger the price tier. |
max_weight_grams | Decimal | Upper limit for the price tier (can be null for highest tier). |
price_per_gram | Decimal | The unit price applied when weight falls within this tier. |
tier_name | String | Label for the pricing tier (e.g., "1/8th", "Half O"). |
Sources: db/migrations/20250228000001_pos_weight_shrinkage_loyalty_consolidated.json:step_5, db/migrations/20250228000001_pos_weight_shrinkage_loyalty_consolidated.json:step_23
Accountability and Security
Every sensitive action in the POS—such as price overrides, refunds, or voids—is subject to Role-Based Access Control (RBAC) and mandatory audit logging.
Role Permissions
- Staff/Cashier: Perform standard sales and basic customer additions.
- Manager/Supervisor: Authorized for price overrides, refunds, inventory adjustments, and voiding saved orders.
- Owner: Full access including billing, privacy presets, and staff management.
Sources: scripts/help-center-data.ts:74-85, scripts/help-center-data.ts:685-695, testsprite_tests/standard_prd.json:35-45
Audit Trail
The system maintains an immutable system_audit_log. Any inventory change or financial adjustment records the user, timestamp, IP address, and old vs. new values.
Customer Credit Management
The POS includes a built-in credit system allowing "Pay Later" transactions. Owners can set credit limits per customer, and the system performs real-time utilization checks during checkout.
- Credit Basics: Sales can be recorded as "Charge to Account" if the customer has sufficient remaining credit.
- Payments: The POS allows recording payments against outstanding balances directly from the customer profile.
- Limits: If a sale exceeds the customer's
credit_limit, the transaction is blocked.
Sources: README.md:13-18, scripts/help-center-data.ts:592-605, app/(app)/help/page.tsx:145-155
Operational Continuity (Offline Mode)
DRX is designed as a "local-first" system. Sales data is stored on the device first, allowing transactions to continue during internet outages.
- Local Storage: Sales are written to the device's local database.
- Automatic Sync: When internet is restored, the system automatically synchronizes local transactions with the server.
- Data Safety: Users are cautioned not to uninstall the app while offline to prevent data loss of unsynced sales.
Sources: scripts/help-center-data.ts:25-35, scripts/help-center-data.ts:258-265, README.md:23