Architecture & Core Concepts

Tracepos is designed from the ground up as an Accounting-First, Multi-Tenant Retail Engine. Unlike simple catalog APIs, every transaction processed via the Tracepos Public API adheres to rigorous principles of double-entry bookkeeping, strict multi-branch scoping, and real-time inventory reconciliation.

1. Double-Entry Accounting by Design

Every commercial action in a retail business has financial implications. When you record a sale, purchase, payment, or expense via the API, Tracepos does not merely update a status flag; it automatically posts balanced Journal Entries across your chart of accounts:

[ POST /sales ]
       |
       +---> Debit: Cash / POS Clearing Account (Assets)
       +---> Debit: Cost of Goods Sold (Expenses)
       +---> Credit: Sales Revenue (Income)
       +---> Credit: Sales Tax Payable (Liabilities)
       +---> Credit: Inventory Asset (Assets)

Key Architectural Benefits

  • Audit-Ready Ledgers: No end-of-month manual reconciliation between inventory and accounting software.
  • Real-Time P&L & Balance Sheet: Revenue, cost of sales, and margins update immediately upon order creation.
  • Party Balances: Customer credit balances and supplier payables update synchronously with each invoice.

2. Multi-Tenant Isolation

Tracepos employs strict multi-tenant isolation at the database level:

  • Every data model (orders, products, customers, payments, journal_entries) carries an immutable company_id.
  • Tenant identification is derived securely from your authenticated Warehouse API Key; client payloads cannot spoof or override company_id.
  • Global scopes enforce tenant isolation, ensuring zero data leakage across different merchant organizations.

3. Warehouse-Scoped Outlets

Multi-branch retail chains operate stores in multiple locations (e.g. Lagos Island, Ikeja, Abuja). Tracepos handles this through Warehouse Scoping:

                          [ Company Tenant ]
                                  |
            +---------------------+---------------------+
            |                                           |
    [ Lagos Warehouse ]                         [ Abuja Warehouse ]
     - API Key #1                                - API Key #2
     - Local Stock: 50 pcs                       - Local Stock: 120 pcs
     - Local Pricing / Currency                  - Local Pricing / Currency
     - Till / Cash Drawer A                      - Till / Cash Drawer B
  • Stock Independence: A product exists once in your catalog, but maintains distinct physical inventory counts in each warehouse (product_details).
  • Targeted Deductions: Calling POST /sales with Lagos API keys deducts inventory specifically from the Lagos warehouse and credits Lagos cashbook accounts.

4. FIFO & Batch Inventory Tracking

For FMCG goods, supermarkets, and pharmaceuticals, Tracepos implements automatic First-In, First-Out (FIFO) batch management:

  • Batches expiring soonest are prioritized automatically during order fulfillment.
  • When an order quantity spans across multiple batches, Tracepos automatically splits the order line items across the respective batches, maintaining precise cost price and expiration records.

5. Multi-Tier Unit Conversion Engine

Retailers frequently purchase goods in bulk (e.g. cartons or pallets) and sell them in smaller units (e.g. pieces, packs):

  • Base Unit: The smallest atomic unit of stock (e.g. Pcs, Kg, Liter).
  • Additional Units: Units with mathematical operators (e.g. 1 Carton = 24 Pcs).
  • The API supports specifying selected_unit_id in line items; Tracepos handles stock conversion factors and alternative pricing automatically behind the scenes.

6. Asynchronous Real-Time Event Streaming

To maintain lightning-fast response times for POS cashiers, Tracepos uses decoupled asynchronous event dispatching:

  • When a sale or stock adjustment is committed, the HTTP response returns immediately to the client.
  • In the background, Tracepos dispatches webhook payloads via queued workers (dispatchAfterResponse), guaranteeing that network delays in third-party webhook receivers never slow down in-store cashiers.