Transaction Engine
Relevant source files
The following files were used as context for generating this wiki page:
The Transaction Engine is the core component of the DRX CRM platform, responsible for orchestrating the lifecycle of sales, inventory movements, and financial accountability. It provides a robust, privacy-first infrastructure for processing transactions, handling both unit-based and weight-based retail operations. The engine ensures data integrity through atomic operations, immutable audit trails, and role-based access control (RBAC).
Within the DRX ecosystem, the engine facilitates complex retail workflows including fractional sales, automated loyalty discounting, and bulk pricing tiers. It operates as a bridge between the Point of Sale (POS) interface and the underlying PostgreSQL database, utilizing specialized Stored Procedures (RPCs) to maintain consistency across sales records, inventory stock levels, and customer loyalty profiles.
Sources: README.md:1-25, testsprite_tests/standard_prd.json:5-15
Core Transaction Logic
The engine's primary execution point is the process_weight_based_checkout function. This procedure manages the transition of a cart from a temporary state to a permanent record. It performs several critical steps: generating unique order numbers, validating real-time stock levels, calculating taxes and fees, and applying customer-specific loyalty discounts.
Checkout Workflow
The following diagram illustrates the sequential logic executed during a checkout transaction:
This flow ensures that no transaction is completed unless inventory is successfully decremented and the business context is verified.
Sources: db/migrations/20250228000001_pos_weight_shrinkage_loyalty_consolidated.sql:572-748, app/(app)/help/page.tsx:75-95
Inventory and Weight Management
A distinguishing feature of the Transaction Engine is its native support for weight-based tracking. This allows for fractional sales (e.g., 3.5g of a product) where the engine automatically converts units and manages "canonical stock" in grams.
Inventory Data Model
| Field | Type | Description |
|---|---|---|
base_unit | VARCHAR(10) | The primary measurement unit (e.g., 'g' for grams). |
convert_to_grams | DECIMAL | Multiplier to convert stock to the base gram unit. |
inventory_in_grams | DECIMAL | The actual weight-based stock available. |
allow_fractional | BOOLEAN | Flag to permit sales of non-integer quantities. |
price_per_gram | DECIMAL | Base pricing used for bulk calculation. |
Sources: db/migrations/20250228000001_pos_weight_shrinkage_loyalty_consolidated.sql:47-53, scripts/help-center-data.ts:285-300
Stock Movement and Shrinkage
The engine handles non-sale stock changes through the record_shrinkage_event function. This provides a mechanism for logging personal use, damaged goods, or inventory variances discovered during random checks. Every movement is recorded in the stock_movements table, creating an immutable trail of why inventory increased or decreased.
Sources: db/migrations/20250228000001_pos_weight_shrinkage_loyalty_consolidated.sql:85-103, db/migrations/20250228000001_pos_weight_shrinkage_loyalty_consolidated.sql:197-270
Pricing and Loyalty Systems
The Transaction Engine dynamically calculates pricing based on business rules and customer history. It supports two primary discount mechanisms:
- Bulk Pricing Rules: The
get_bulk_pricingfunction identifies the correct price per gram based on the quantity sold, allowing for tiered pricing (e.g., lower price per gram when purchasing 10g or more). - Loyalty Program: The engine tracks a customer's
purchase_countandtotal_purchases. Theupdate_customer_loyalty_tierfunction automatically promotes customers through tiers (None, Silver, Gold, Platinum) based on transaction history.
Tier Logic Configuration
The system uses a JSONB configuration for flexibility:
{
"silver": {"min_purchases": 5, "discount": 0.05},
"gold": {"min_purchases": 15, "discount": 0.10},
"platinum": {"min_purchases": 30, "discount": 0.15}
}
Sources: db/migrations/20250228000001_pos_weight_shrinkage_loyalty_consolidated.sql:350-425, db/migrations/20250228000001_pos_weight_shrinkage_loyalty_consolidated.json:step_8
Accountability and Audit Logging
For security and compliance, the engine implements a strict "Trust but Verify" policy. Every sensitive action—including price overrides, voids, and inventory adjustments—is captured in the system_audit_log.
Audit Log Structure
The logs capture the state of data before and after a change, the user responsible, and the IP address from which the transaction originated.
Sources: db/migrations/20250228000001_pos_weight_shrinkage_loyalty_consolidated.sql:78-83, testsprite_tests/standard_prd.json:30-45
Summary
The DRX Transaction Engine provides a high-integrity framework for processing retail sales and managing inventory. By centralizing logic in database-level RPC functions, the system maintains strict multi-tenant isolation and ensures that financial records remain immutable. Its specialized support for weight-based sales and automated loyalty logic makes it particularly suited for modern, regulated retail environments.