# Architecture

## Boundaries

1. **Organisation and Access** — legal entity, branches, users, roles, permissions, maker-checker.
2. **Party** — one legal party with multiple roles; no forced customer/vendor duplication.
3. **Accounting** — chart, periods, journals, sub-ledger dimensions, posting and reversal services.
4. **Commercial** — quotations, contracts, rates, customer billing.
5. **Procurement** — vendor bills, debit/credit notes, payments and vendor recovery.
6. **Transport Operations** — jobs, trips, routes, vehicles, drivers, POD and trip costs.
7. **Tax** — configurable UAE VAT codes, tax periods, reconciliation and exception reporting.
8. **Integration** — REST API, e-invoice provider adapters, banks, GPS, OCR and AI.
9. **Documents and Reporting** — versioned PDFs, statements, GL and operational profitability.

## Non-negotiable invariants

- Posted journals have equal debit and credit totals.
- Posted journals and financial content are immutable.
- Party balances are calculated from posted journal lines.
- Customer and vendor ledgers are independent even for the same party.
- Contra requires an explicit approved document and never occurs automatically.
- Financial posting executes inside a database transaction with record locks.
- Tax treatment comes from authorised tax-code configuration, not service-name guesses.
- External e-invoice submission is provider-adapter based and production-disabled by default.

## Deployment shape

A modular monolith is selected for the first production release. It keeps financial transactions atomic and auditable while exposing versioned integration APIs. Queue workers handle non-transactional work after commit: email, PDF rendering, exports, OCR, AI suggestions, and provider submissions.
