Expenses Phase A In-progress
Expenses is the merchant's books. It tracks where money lives (cash drawers, bank, QR, mobile-POS accounts), records every money movement as a balanced double-entry voucher, and classifies income and expense by category — most of it posted automatically when a sale is paid, a purchase order is received, or stock moves.
1. Identity
| Property | Value |
|---|---|
| Module ID | CORE-12 |
| Tier | Core |
| Status | In-progress |
| Phase | P1 (auto-posting) shipped · P2 (manual vouchers, accounts UI, transfers) emerging |
| Priority | MEDIUM |
| Primary users | Owner · Accountant · Manager |
2. Purpose & Scope
| Included | Excluded |
|---|---|
| Money accounts / wallets (Cash, Bank, QR, Mobile-POS) | Payment gateway processing (Payment module) |
| Double-entry vouchers (receipt, payment, transfer, adjustment) | Tax invoice issuance (Invoice module) |
| Income / expense category hierarchy | Stock quantity & costing math (Inventory module) |
| Automatic posting from sales, purchases, stock movements | Budgeting, P&L statements, cash-flow forecasting (future) |
| Voucher void by balanced reversal | Recurring / scheduled expenses (future) |
| Per-merchant account isolation | Receipt-image capture / OCR (future) |
3. Capabilities
| Capability | What the user can do | Status |
|---|---|---|
| Money accounts | Hold balances across cash drawers, bank, QR, and mobile-POS accounts; one default account per type | In-progress |
| Auto income on sale paid | Sale revenue books a receipt voucher automatically, no manual entry | Built |
| Auto purchase posting | Receiving a purchase order books a payment voucher to the vendor automatically | Built |
| Auto stock posting | Cost of goods sold and stock adjustments post to internal control accounts automatically | Built |
| Categories | Classify money movements with 14 seeded categories plus custom merchant categories | Built |
| Manual vouchers | Draft, approve, issue, and void vouchers by hand | In-progress |
| Account transfers | Move money between accounts as a balanced transfer voucher | In-progress |
| Shift cash movements | Record pay-ins, pay-outs, and safe drops against a POS session | Planned |
4. Module Dependencies
| Depends on | Why |
|---|---|
| Payment | A successful payment triggers an automatic receipt voucher for the sale |
| Inventory | Receiving a purchase order, selling stock, and stock adjustments trigger automatic vouchers |
| Commerce (Merchant) | A new merchant gets its default accounts reconciled automatically |
| Reports | Consumes finance data for financial analytics |
5. Backend Packages
Implementation detail lives in the developer docs — this section only maps the module to the service that powers it.
| Package | Role | Developer docs |
|---|---|---|
@nx/finance | Double-entry bookkeeping engine: accounts, vouchers, ledger lines, categories, event-driven posting | finance |
6. Key User Flows
Automatic receipt on a paid sale
Manual transfer between accounts
7. Roles & Permissions
| Role | Can | Cannot |
|---|---|---|
| Owner | View and manage own merchants' accounts, vouchers, and categories | See other organizers' merchants |
| Accountant / Manager | Record vouchers, transfers, and classify movements within their merchant | Manage payment-gateway credentials |
| Super Admin / Admin | See accounts across all merchants | — |
Account visibility is merchant-scoped: non-admins only see accounts of merchants they are granted. See the finance integration notes for the authorization contract.
8. Status & Roadmap
| Phase | Capabilities |
|---|---|
| P1 | Automatic posting from sale payments, purchase-order receipts, and stock movements; 14 seeded categories; default-account reconciliation on new merchant |
| P2 | Account management UI, manual draft→issue voucher lifecycle, account transfers, custom categories |
| P3 | Shift cash movements (pay-in / pay-out / safe drop), budgeting, P&L, cash-flow forecasting |
Status honesty: auto-posting (P1) is live and verified in code. The manual account/voucher UI and transfers (P2) are partially wired — the posting engine supports them, but merchant-facing screens and some safeguards are still maturing (see Test Cases for verified vs gap items).