# Architecture and database summary

## Design rules

- Controllers validate requests and delegate business mutations to services.
- `InventoryService` is the only transaction engine allowed to change warehouse quantities. Every movement also writes an immutable `stock_ledgers` row.
- `AccountingService` is the common double-entry posting engine. It rejects unbalanced journals.
- `VatCalculationService` and BCMath handle monetary arithmetic; database amounts use decimal columns.
- Finalized documents are not editable. Corrections use returns, adjustments, receipts, payments, or reversing business documents.
- Transaction rows store price, cost, VAT, discount, names, unit, and conversion snapshots, so master-data changes do not rewrite history.
- `DocumentSequenceService` uses transactions and row locks to generate unique numbers by document, branch, and financial year.
- `FinancialPeriodService` rejects dates outside an open financial year or inside a locked period.

## Principal data areas

| Area | Main tables |
|---|---|
| Security | `users`, `roles`, `permissions`, `user_roles`, `role_permissions`, `user_branches`, `login_histories`, `audit_logs` |
| Configuration | `company_profiles`, `vat_settings`, `general_settings`, `branches`, `warehouses`, `financial_years`, `document_sequences` |
| Master data | `products`, `product_units`, `product_barcodes`, `product_price_histories`, `categories`, `brands`, `units`, `customers`, `suppliers` |
| Inventory | `warehouse_stocks`, `stock_ledgers`, `inventory_batches`, `inventory_openings`, `stock_adjustments`, `stock_transfers` |
| Sales | `sales`, `sale_items`, `sales_payments`, `sales_returns`, `sales_return_items`, `customer_ledgers` |
| Purchase | `purchases`, `purchase_items`, `purchase_payments`, `purchase_returns`, `purchase_return_items`, `supplier_ledgers` |
| Accounts | `chart_of_accounts`, `journal_entries`, `journal_entry_lines`, `receipts`, `payments`, `expenses`, allocation tables |
| Van | `van_sessions`, `van_loadings`, `van_loading_items`, `van_closings`; each van is also a normal warehouse |
| Operations | `backups`, opening balance tables, translation dictionaries |

## Connected posting flows

Purchase finalization posts inventory and input VAT against cash/bank/payable, updates weighted cost, stock summary, stock ledger, supplier ledger, and journal.

Sale finalization validates period, stock, credit, and permission; snapshots cost/profit; reduces stock; posts cash/bank/receivable against revenue and output VAT plus COGS/inventory; writes the customer ledger; and freezes the ZATCA Phase 1 TLV.

Returns reverse quantities, VAT, subledger positions, and the associated accounting direction without deleting the source document. Van loading uses the standard warehouse-transfer engine, so main and van stock reconcile through the same ledger.

## Extension boundary

Phase 2 can be added later behind a separate e-invoicing adapter and submission queue. Existing invoices already retain the stable seller, buyer, totals, timestamps, and line snapshots needed for that work, but no Phase 2 behavior is present now.