# x-nfo/pos architecture

> Architecture diagram of the GitHub repository x-nfo/pos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/x-nfo/pos
- Repository: https://github.com/x-nfo/pos

## Overview

This is a Laravel, Inertia, and React point-of-sale and retail-operations application. The main workflow runs from cashier product search and cart management through pricing, checkout, payment, transaction recording, and receipt generation; offline transactions synchronize when connectivity returns. Separate product areas cover stock and purchasing, customer finance, CRM and loyalty, public ordering, reporting, and administration. The graph uses sampled source references and README capabilities; unsampled subsystem internals are represented at their existing directory paths, and relationships not evidenced are omitted.

Main entry points: [`app/Http/Controllers/Api/PosApiController.php`](https://github.com/x-nfo/pos/blob/main/app/Http/Controllers/Api/PosApiController.php) (POS API), [`resources/js/Components/POS/index.jsx`](https://github.com/x-nfo/pos/blob/main/resources/js/Components/POS/index.jsx) (POS interface), [`app/Services/CheckoutService.php`](https://github.com/x-nfo/pos/blob/main/app/Services/CheckoutService.php) (Checkout), [`app/Models/Transaction.php`](https://github.com/x-nfo/pos/blob/main/app/Models/Transaction.php) (Transaction records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sales["Sales and POS"]
  node_pos_ui["POS interface<br/>[index.jsx]"]
  node_pos_api["POS API"]
  node_cart[("Cart and transactions<br/>[Cart.php]")]
  node_pricing["Promotion pricing<br/>[PricingService.php]"]
  node_checkout["Checkout"]
  node_payment["Payment gateways"]
  node_transaction[("Transaction records<br/>[Transaction.php]")]
  node_printing["Receipt printing"]
  node_offline["Offline sync<br/>[syncEngine.js]"]
end

subgraph group_inventory["Inventory and purchasing"]
  node_product[("Product catalog<br/>[Product.php]")]
  node_warehouse[("Warehouse stock<br/>[Warehouse.php]")]
  node_stock_ops["Stock operations"]
  node_purchasing["Purchasing"]
end

subgraph group_customers["Customers and finance"]
  node_customer[("Customer and loyalty<br/>[Customer.php]")]
  node_crm["CRM automation"]
  node_whatsapp["WhatsApp gateway<br/>[server.js]"]
  node_finance["Receivables and payables"]
end

subgraph group_channels["Channels and reporting"]
  node_public_order["Public catalog orders"]
  node_reports["Reports and exports"]
end

subgraph group_platform["Platform and administration"]
  node_admin["Administration"]
  node_audit["Audit logging"]
  node_settings[("Store settings<br/>[Setting.php]")]
end

node_cashier(("Cashier"))
node_api_client(("Mobile or partner client"))
node_buyer(("Public shopper"))

node_cashier -->|"operates"| node_pos_ui
node_pos_ui -->|"submits POS requests"| node_pos_api
node_pos_api -->|"manages cart"| node_cart
node_pos_api -->|"invokes checkout"| node_checkout
node_checkout -.->|"applies promotions"| node_pricing
node_checkout -.->|"creates payment"| node_payment
node_payment -->|"charges transaction"| node_transaction
node_checkout -.->|"records sale"| node_transaction
node_transaction -.->|"renders receipt"| node_printing
node_pos_ui -->|"queues offline sales"| node_offline
node_offline -.->|"syncs transactions"| node_pos_api
node_pos_ui -->|"searches products"| node_product
node_stock_ops -.->|"records stock changes"| node_warehouse
node_purchasing -.->|"receives stock"| node_stock_ops
node_api_client -->|"uses POS API"| node_pos_api
node_buyer -->|"places catalog order"| node_public_order
node_public_order -->|"prices catalog items"| node_pricing
node_public_order -->|"selects branch"| node_warehouse
node_crm -->|"sends campaigns"| node_whatsapp
node_crm -->|"segments customers"| node_customer
node_reports -->|"analyzes sales"| node_transaction
node_admin -.->|"records changes"| node_audit
node_printing -->|"reads print settings"| node_settings

click node_pos_ui "https://github.com/x-nfo/pos/blob/main/resources/js/Components/POS/index.jsx"
click node_pos_api "https://github.com/x-nfo/pos/blob/main/app/Http/Controllers/Api/PosApiController.php"
click node_cart "https://github.com/x-nfo/pos/blob/main/app/Models/Cart.php"
click node_pricing "https://github.com/x-nfo/pos/blob/main/app/Services/PricingService.php"
click node_checkout "https://github.com/x-nfo/pos/blob/main/app/Services/CheckoutService.php"
click node_payment "https://github.com/x-nfo/pos/blob/main/app/Services/Payments/PaymentGatewayManager.php"
click node_transaction "https://github.com/x-nfo/pos/blob/main/app/Models/Transaction.php"
click node_printing "https://github.com/x-nfo/pos/blob/main/app/Services/ThermalPrintService.php"
click node_offline "https://github.com/x-nfo/pos/blob/main/resources/js/Utils/syncEngine.js"
click node_product "https://github.com/x-nfo/pos/blob/main/app/Models/Product.php"
click node_warehouse "https://github.com/x-nfo/pos/blob/main/app/Models/Warehouse.php"
click node_stock_ops "https://github.com/x-nfo/pos/blob/main/app/Services/StockMutationService.php"
click node_purchasing "https://github.com/x-nfo/pos/blob/main/app/Services/PurchaseOrderService.php"
click node_customer "https://github.com/x-nfo/pos/blob/main/app/Models/Customer.php"
click node_crm "https://github.com/x-nfo/pos/blob/main/app/Services/CrmAutomationService.php"
click node_whatsapp "https://github.com/x-nfo/pos/blob/main/whatsapp-service/server.js"
click node_finance "https://github.com/x-nfo/pos/blob/main/app/Http/Controllers/Apps/ReceivableController.php"
click node_public_order "https://github.com/x-nfo/pos/blob/main/app/Http/Controllers/PublicCatalogController.php"
click node_reports "https://github.com/x-nfo/pos/tree/main/app/Http/Controllers/Reports"
click node_admin "https://github.com/x-nfo/pos/tree/main/app/Http/Controllers/Apps"
click node_audit "https://github.com/x-nfo/pos/blob/main/app/Services/AuditLogService.php"
click node_settings "https://github.com/x-nfo/pos/blob/main/app/Models/Setting.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_pos_ui,node_pos_api,node_cart,node_pricing,node_checkout,node_payment,node_transaction,node_printing,node_offline,node_api_client toneBlue
class node_product,node_warehouse,node_stock_ops,node_purchasing toneAmber
class node_customer,node_crm,node_whatsapp,node_finance toneMint
class node_public_order,node_reports toneRose
class node_admin,node_audit,node_settings,node_cashier,node_buyer toneIndigo
```

## Components

### Sales and POS

- [POS interface](https://github.com/x-nfo/pos/blob/main/resources/js/Components/POS/index.jsx): `resources/js/Components/POS/index.jsx`
- [POS API](https://github.com/x-nfo/pos/blob/main/app/Http/Controllers/Api/PosApiController.php): `app/Http/Controllers/Api/PosApiController.php`
- [Cart and transactions](https://github.com/x-nfo/pos/blob/main/app/Models/Cart.php): `app/Models/Cart.php`
- [Promotion pricing](https://github.com/x-nfo/pos/blob/main/app/Services/PricingService.php): `app/Services/PricingService.php`
- [Checkout](https://github.com/x-nfo/pos/blob/main/app/Services/CheckoutService.php): `app/Services/CheckoutService.php`
- [Payment gateways](https://github.com/x-nfo/pos/blob/main/app/Services/Payments/PaymentGatewayManager.php): `app/Services/Payments/PaymentGatewayManager.php`
- [Transaction records](https://github.com/x-nfo/pos/blob/main/app/Models/Transaction.php): `app/Models/Transaction.php`
- [Receipt printing](https://github.com/x-nfo/pos/blob/main/app/Services/ThermalPrintService.php): `app/Services/ThermalPrintService.php`
- [Offline sync](https://github.com/x-nfo/pos/blob/main/resources/js/Utils/syncEngine.js): `resources/js/Utils/syncEngine.js`

### Inventory and purchasing

- [Product catalog](https://github.com/x-nfo/pos/blob/main/app/Models/Product.php): `app/Models/Product.php`
- [Warehouse stock](https://github.com/x-nfo/pos/blob/main/app/Models/Warehouse.php): `app/Models/Warehouse.php`
- [Stock operations](https://github.com/x-nfo/pos/blob/main/app/Services/StockMutationService.php): `app/Services/StockMutationService.php`
- [Purchasing](https://github.com/x-nfo/pos/blob/main/app/Services/PurchaseOrderService.php): `app/Services/PurchaseOrderService.php`

### Customers and finance

- [Customer and loyalty](https://github.com/x-nfo/pos/blob/main/app/Models/Customer.php): `app/Models/Customer.php`
- [CRM automation](https://github.com/x-nfo/pos/blob/main/app/Services/CrmAutomationService.php): `app/Services/CrmAutomationService.php`
- [WhatsApp gateway](https://github.com/x-nfo/pos/blob/main/whatsapp-service/server.js): `whatsapp-service/server.js`
- [Receivables and payables](https://github.com/x-nfo/pos/blob/main/app/Http/Controllers/Apps/ReceivableController.php): `app/Http/Controllers/Apps/ReceivableController.php`

### Channels and reporting

- [Public catalog orders](https://github.com/x-nfo/pos/blob/main/app/Http/Controllers/PublicCatalogController.php): `app/Http/Controllers/PublicCatalogController.php`
- [Reports and exports](https://github.com/x-nfo/pos/tree/main/app/Http/Controllers/Reports): `app/Http/Controllers/Reports`

### Platform and administration

- [Administration](https://github.com/x-nfo/pos/tree/main/app/Http/Controllers/Apps): `app/Http/Controllers/Apps`
- [Audit logging](https://github.com/x-nfo/pos/blob/main/app/Services/AuditLogService.php): `app/Services/AuditLogService.php`
- [Store settings](https://github.com/x-nfo/pos/blob/main/app/Models/Setting.php): `app/Models/Setting.php`

### Other components

- **Cashier**
- **Mobile or partner client**
- **Public shopper**

## Connections

- Cashier → POS interface: operates (evidence: `README.md`)
- POS interface → POS API: submits POS requests (evidence: `README.md`)
- POS API → Cart and transactions: manages cart (evidence: `app/Http/Controllers/Api/PosApiController.php`)
- POS API → Checkout: invokes checkout (evidence: `app/Http/Controllers/Api/PosApiController.php`)
- Checkout → Promotion pricing: applies promotions
- Checkout → Payment gateways: creates payment
- Payment gateways → Transaction records: charges transaction (evidence: `app/Services/Payments/PaymentGatewayManager.php`)
- Checkout → Transaction records: records sale
- Transaction records → Receipt printing: renders receipt (evidence: `app/Services/ThermalPrintService.php`)
- POS interface → Offline sync: queues offline sales (evidence: `README.md`)
- Offline sync → POS API: syncs transactions
- POS interface → Product catalog: searches products (evidence: `README.md`)
- Stock operations → Warehouse stock: records stock changes
- Purchasing → Stock operations: receives stock
- Mobile or partner client → POS API: uses POS API (evidence: `README.md`)
- Public shopper → Public catalog orders: places catalog order (evidence: `README.md`)
- Public catalog orders → Promotion pricing: prices catalog items (evidence: `app/Http/Controllers/PublicCatalogController.php`)
- Public catalog orders → Warehouse stock: selects branch (evidence: `app/Http/Controllers/PublicCatalogController.php`)
- CRM automation → WhatsApp gateway: sends campaigns (evidence: `app/Services/CrmAutomationService.php`)
- CRM automation → Customer and loyalty: segments customers (evidence: `app/Services/CrmAutomationService.php`)
- Reports and exports → Transaction records: analyzes sales (evidence: `README.md`)
- Administration → Audit logging: records changes (evidence: `app/Http/Controllers/Apps/SalesReturnController.php`)
- Receipt printing → Store settings: reads print settings (evidence: `app/Services/ThermalPrintService.php`)
