# brainwise-dev/posnext architecture

> Architecture diagram of the GitHub repository brainwise-dev/posnext, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/brainwise-dev/posnext
- Repository: https://github.com/brainwise-dev/posnext

## Overview

POS Next is an ERPNext point-of-sale application with a Vue client and Frappe backend. The main user workflow is cashier login, item/customer selection, cart and promotion handling, checkout/payment, and receipt printing; shifts, returns, drafts, and offline selling are related product stages. Backend capabilities include invoice and item APIs, authorization, and reporting. The source excerpts show application startup, offline-worker behavior, and authorization internals; other feature links below rely on the README, so unsampled implementation details are not inferred.

Main entry points: [`POS/src/pages/POSSale.vue`](https://github.com/brainwise-dev/posnext/blob/develop/POS/src/pages/POSSale.vue) (Sales workflow), [`pos_next/api/authorization.py`](https://github.com/brainwise-dev/posnext/blob/develop/pos_next/api/authorization.py) (Authorization API), [`pos_next/authorization/gate.py`](https://github.com/brainwise-dev/posnext/blob/develop/pos_next/authorization/gate.py) (Document gate), [`POS/src/App.vue`](https://github.com/brainwise-dev/posnext/blob/develop/POS/src/App.vue) (Vue application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["POS client"]
  node_app["Vue application<br/>[App.vue]"]
  node_sale["Sales workflow<br/>[POSSale.vue]"]
  node_invoice_ui["Invoice management"]
  node_session["Session identity<br/>[session.js]"]
  node_user["User identity<br/>[user.js]"]
  node_currency["Currency formatting<br/>[currency.js]"]
  node_translations["Translations<br/>[translation.ts]"]
  node_logger["Client logging<br/>[logger.js]"]
end

subgraph group_offline["Offline operation"]
  node_offline_state[("Offline state<br/>[offlineState.js]")]
  node_translation_cache[("Translation cache")]
  node_worker_client["Worker client<br/>[workerClient.js]"]
  node_offline_worker["Offline worker<br/>[offline.worker.js]"]
  node_offline_sync["Offline sync<br/>[sync.js]"]
end

subgraph group_backend["ERPNext services"]
  node_invoice_api["Invoice services<br/>[invoices.py]"]
  node_items_api["Item services<br/>[items.py]"]
  node_credit_sales["Credit sales<br/>[credit_sales.py]"]
  node_shift_service["Shift management<br/>[shifts.py]"]
  node_promotions["Promotions and coupons<br/>[offers.py]"]
  node_reports["POS reports"]
  node_sales_commission["Sales commissions"]
  node_invoice_hooks["Invoice hooks"]
end

subgraph group_governance["Authorization"]
  node_authorization_api["Authorization API<br/>[authorization.py]"]
  node_auth_gate["Document gate<br/>[gate.py]"]
  node_auth_policy["Approval policy<br/>[policy.py]"]
  node_auth_pin["Approver PIN<br/>[pin.py]"]
  node_auth_registry["Action registry<br/>[registry.py]"]
  node_auth_grants["Authorization grants<br/>[grants.py]"]
  node_auth_log["Authorization audit<br/>[log.py]"]
end

node_cashier(("Cashier"))

node_cashier -->|"selects and checks out"| node_sale
node_sale -->|"submits sales"| node_invoice_api
node_sale -->|"searches items"| node_items_api
node_sale -->|"applies offers"| node_promotions
node_sale -->|"requests credit approval"| node_credit_sales
node_sale -->|"opens and closes shifts"| node_shift_service
node_sale -->|"manages invoices"| node_invoice_ui
node_invoice_ui -->|"processes returns"| node_invoice_api
node_sale -->|"views shift insights"| node_reports
node_app -->|"initializes session"| node_session
node_app -->|"initializes user"| node_user
node_app -->|"initializes worker"| node_worker_client
node_worker_client -->|"reads offline state"| node_offline_state
node_offline_worker -.->|"persists queued sales"| node_offline_state
node_offline_worker -.->|"synchronizes queued data"| node_offline_sync
node_translations -->|"uses cached translations"| node_translation_cache
node_authorization_api -->|"queries gate policy"| node_auth_gate
node_authorization_api -->|"resolves approvers"| node_auth_policy
node_authorization_api -->|"looks up actions"| node_auth_registry
node_authorization_api -->|"verifies PIN"| node_auth_pin
node_authorization_api -->|"records decisions"| node_auth_log
node_auth_gate -->|"checks grants"| node_auth_grants
node_auth_gate -->|"resolves rules"| node_auth_policy
node_auth_gate -->|"dispatches actions"| node_auth_registry
node_auth_gate -->|"records enforcement"| node_auth_log
node_invoice_hooks -->|"uses credit-sale hooks"| node_credit_sales
node_invoice_hooks -->|"applies commissions"| node_sales_commission

click node_app "https://github.com/brainwise-dev/posnext/blob/develop/POS/src/App.vue"
click node_sale "https://github.com/brainwise-dev/posnext/blob/develop/POS/src/pages/POSSale.vue"
click node_invoice_ui "https://github.com/brainwise-dev/posnext/blob/develop/POS/src/components/invoices/InvoiceManagement.vue"
click node_session "https://github.com/brainwise-dev/posnext/blob/develop/POS/src/data/session.js"
click node_user "https://github.com/brainwise-dev/posnext/blob/develop/POS/src/data/user.js"
click node_currency "https://github.com/brainwise-dev/posnext/blob/develop/POS/src/utils/currency.js"
click node_translations "https://github.com/brainwise-dev/posnext/blob/develop/POS/src/utils/translation.ts"
click node_logger "https://github.com/brainwise-dev/posnext/blob/develop/POS/src/utils/logger.js"
click node_offline_state "https://github.com/brainwise-dev/posnext/blob/develop/POS/src/utils/offline/offlineState.js"
click node_translation_cache "https://github.com/brainwise-dev/posnext/blob/develop/POS/src/utils/offline/translationCache.js"
click node_worker_client "https://github.com/brainwise-dev/posnext/blob/develop/POS/src/utils/offline/workerClient.js"
click node_offline_worker "https://github.com/brainwise-dev/posnext/blob/develop/POS/src/workers/offline.worker.js"
click node_offline_sync "https://github.com/brainwise-dev/posnext/blob/develop/POS/src/utils/offline/sync.js"
click node_invoice_api "https://github.com/brainwise-dev/posnext/blob/develop/pos_next/api/invoices.py"
click node_items_api "https://github.com/brainwise-dev/posnext/blob/develop/pos_next/api/items.py"
click node_credit_sales "https://github.com/brainwise-dev/posnext/blob/develop/pos_next/api/credit_sales.py"
click node_shift_service "https://github.com/brainwise-dev/posnext/blob/develop/pos_next/api/shifts.py"
click node_promotions "https://github.com/brainwise-dev/posnext/blob/develop/pos_next/api/offers.py"
click node_reports "https://github.com/brainwise-dev/posnext/tree/develop/pos_next/pos_next/report"
click node_authorization_api "https://github.com/brainwise-dev/posnext/blob/develop/pos_next/api/authorization.py"
click node_auth_gate "https://github.com/brainwise-dev/posnext/blob/develop/pos_next/authorization/gate.py"
click node_auth_policy "https://github.com/brainwise-dev/posnext/blob/develop/pos_next/authorization/policy.py"
click node_auth_pin "https://github.com/brainwise-dev/posnext/blob/develop/pos_next/authorization/pin.py"
click node_auth_registry "https://github.com/brainwise-dev/posnext/blob/develop/pos_next/authorization/registry.py"
click node_auth_grants "https://github.com/brainwise-dev/posnext/blob/develop/pos_next/authorization/grants.py"
click node_auth_log "https://github.com/brainwise-dev/posnext/blob/develop/pos_next/authorization/log.py"
click node_sales_commission "https://github.com/brainwise-dev/posnext/blob/develop/pos_next/pos_next/utils/sales_person_commission.py"
click node_invoice_hooks "https://github.com/brainwise-dev/posnext/blob/develop/pos_next/api/sales_invoice_hooks.py"

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_app,node_sale,node_invoice_ui,node_session,node_user,node_currency,node_translations,node_logger toneBlue
class node_offline_state,node_translation_cache,node_worker_client,node_offline_worker,node_offline_sync toneAmber
class node_invoice_api,node_items_api,node_credit_sales,node_shift_service,node_promotions,node_reports,node_sales_commission,node_invoice_hooks toneMint
class node_authorization_api,node_auth_gate,node_auth_policy,node_auth_pin,node_auth_registry,node_auth_grants,node_auth_log toneRose
class node_cashier toneIndigo
```

## Components

### POS client

- [Vue application](https://github.com/brainwise-dev/posnext/blob/develop/POS/src/App.vue): `POS/src/App.vue`
- [Sales workflow](https://github.com/brainwise-dev/posnext/blob/develop/POS/src/pages/POSSale.vue): `POS/src/pages/POSSale.vue`
- [Invoice management](https://github.com/brainwise-dev/posnext/blob/develop/POS/src/components/invoices/InvoiceManagement.vue): `POS/src/components/invoices/InvoiceManagement.vue`
- [Session identity](https://github.com/brainwise-dev/posnext/blob/develop/POS/src/data/session.js): `POS/src/data/session.js`
- [User identity](https://github.com/brainwise-dev/posnext/blob/develop/POS/src/data/user.js): `POS/src/data/user.js`
- [Currency formatting](https://github.com/brainwise-dev/posnext/blob/develop/POS/src/utils/currency.js): `POS/src/utils/currency.js`
- [Translations](https://github.com/brainwise-dev/posnext/blob/develop/POS/src/utils/translation.ts): `POS/src/utils/translation.ts`
- [Client logging](https://github.com/brainwise-dev/posnext/blob/develop/POS/src/utils/logger.js): `POS/src/utils/logger.js`

### Offline operation

- [Offline state](https://github.com/brainwise-dev/posnext/blob/develop/POS/src/utils/offline/offlineState.js): `POS/src/utils/offline/offlineState.js`
- [Translation cache](https://github.com/brainwise-dev/posnext/blob/develop/POS/src/utils/offline/translationCache.js): `POS/src/utils/offline/translationCache.js`
- [Worker client](https://github.com/brainwise-dev/posnext/blob/develop/POS/src/utils/offline/workerClient.js): `POS/src/utils/offline/workerClient.js`
- [Offline worker](https://github.com/brainwise-dev/posnext/blob/develop/POS/src/workers/offline.worker.js): `POS/src/workers/offline.worker.js`
- [Offline sync](https://github.com/brainwise-dev/posnext/blob/develop/POS/src/utils/offline/sync.js): `POS/src/utils/offline/sync.js`

### ERPNext services

- [Invoice services](https://github.com/brainwise-dev/posnext/blob/develop/pos_next/api/invoices.py): `pos_next/api/invoices.py`
- [Item services](https://github.com/brainwise-dev/posnext/blob/develop/pos_next/api/items.py): `pos_next/api/items.py`
- [Credit sales](https://github.com/brainwise-dev/posnext/blob/develop/pos_next/api/credit_sales.py): `pos_next/api/credit_sales.py`
- [Shift management](https://github.com/brainwise-dev/posnext/blob/develop/pos_next/api/shifts.py): `pos_next/api/shifts.py`
- [Promotions and coupons](https://github.com/brainwise-dev/posnext/blob/develop/pos_next/api/offers.py): `pos_next/api/offers.py`
- [POS reports](https://github.com/brainwise-dev/posnext/tree/develop/pos_next/pos_next/report): `pos_next/pos_next/report`
- [Sales commissions](https://github.com/brainwise-dev/posnext/blob/develop/pos_next/pos_next/utils/sales_person_commission.py): `pos_next/pos_next/utils/sales_person_commission.py`
- [Invoice hooks](https://github.com/brainwise-dev/posnext/blob/develop/pos_next/api/sales_invoice_hooks.py): `pos_next/api/sales_invoice_hooks.py`

### Authorization

- [Authorization API](https://github.com/brainwise-dev/posnext/blob/develop/pos_next/api/authorization.py): `pos_next/api/authorization.py`
- [Document gate](https://github.com/brainwise-dev/posnext/blob/develop/pos_next/authorization/gate.py): `pos_next/authorization/gate.py`
- [Approval policy](https://github.com/brainwise-dev/posnext/blob/develop/pos_next/authorization/policy.py): `pos_next/authorization/policy.py`
- [Approver PIN](https://github.com/brainwise-dev/posnext/blob/develop/pos_next/authorization/pin.py): `pos_next/authorization/pin.py`
- [Action registry](https://github.com/brainwise-dev/posnext/blob/develop/pos_next/authorization/registry.py): `pos_next/authorization/registry.py`
- [Authorization grants](https://github.com/brainwise-dev/posnext/blob/develop/pos_next/authorization/grants.py): `pos_next/authorization/grants.py`
- [Authorization audit](https://github.com/brainwise-dev/posnext/blob/develop/pos_next/authorization/log.py): `pos_next/authorization/log.py`

### Other components

- **Cashier**

## Connections

- Cashier → Sales workflow: selects and checks out (evidence: `README.md`)
- Sales workflow → Invoice services: submits sales (evidence: `README.md`)
- Sales workflow → Item services: searches items (evidence: `README.md`)
- Sales workflow → Promotions and coupons: applies offers (evidence: `README.md`)
- Sales workflow → Credit sales: requests credit approval (evidence: `README.md`)
- Sales workflow → Shift management: opens and closes shifts (evidence: `README.md`)
- Sales workflow → Invoice management: manages invoices (evidence: `README.md`)
- Invoice management → Invoice services: processes returns (evidence: `README.md`)
- Sales workflow → POS reports: views shift insights (evidence: `README.md`)
- Vue application → Session identity: initializes session (evidence: `POS/src/main.js`)
- Vue application → User identity: initializes user (evidence: `POS/src/main.js`)
- Vue application → Worker client: initializes worker (evidence: `POS/src/main.js`)
- Worker client → Offline state: reads offline state (evidence: `POS/src/utils/offline/workerClient.js`)
- Offline worker → Offline state: persists queued sales
- Offline worker → Offline sync: synchronizes queued data
- Translations → Translation cache: uses cached translations (evidence: `POS/src/utils/translation.ts`)
- Authorization API → Document gate: queries gate policy (evidence: `pos_next/api/authorization.py`)
- Authorization API → Approval policy: resolves approvers (evidence: `pos_next/api/authorization.py`)
- Authorization API → Action registry: looks up actions (evidence: `pos_next/api/authorization.py`)
- Authorization API → Approver PIN: verifies PIN (evidence: `pos_next/api/authorization.py`)
- Authorization API → Authorization audit: records decisions (evidence: `pos_next/api/authorization.py`)
- Document gate → Authorization grants: checks grants (evidence: `pos_next/authorization/gate.py`)
- Document gate → Approval policy: resolves rules (evidence: `pos_next/authorization/gate.py`)
- Document gate → Action registry: dispatches actions (evidence: `pos_next/authorization/gate.py`)
- Document gate → Authorization audit: records enforcement (evidence: `pos_next/authorization/gate.py`)
- Invoice hooks → Credit sales: uses credit-sale hooks (evidence: `pos_next/api/sales_invoice_hooks.py`)
- Invoice hooks → Sales commissions: applies commissions (evidence: `pos_next/overrides/sales_invoice.py`)