Accounting module
The accounting module is a double-entry general ledger. Payroll, sales and purchasing all post into it. It sits beside those modules rather than inside them: payroll stays the system of record for pay, and the ledger consumes what payroll and the commercial documents produce.
Code lives in backend/src/main/java/com/motorph/payroll/accounting/. Pages are under frontend/src/pages/accounting/, in the sidebar's Accounting group.
The statements and reports are built from posted journal entries. They are tools for a bookkeeper and a CPA, not a claim that a company's books meet any particular BIR requirement. See
reference/compliance/register.yamlfor what is and is not covered.
Data model (V128–V130)
| Table | Purpose |
|---|---|
account | Chart of accounts. Header accounts (is_postable = false) group others. system_key marks seeded control accounts the code posts to (the 22 payroll journal lines, AR, AP, VAT, EWT, cash, bank, ...). |
accounting_period | Calendar months, created the first time something posts into them. OPEN / CLOSED. |
accounting_settings | One row per tenant: the control accounts commercial documents use, plus commerce_auto_post, require_separate_poster and go_live_date. |
journal_entry / journal_entry_line | Entries and their debit/credit lines. Lines carry optional department, customer and supplier dimensions. |
Every table is tenant-scoped (Hibernate @TenantId plus a Postgres RLS policy). New tenants get the default chart from the SQL function accounting_seed_tenant(). The migration runs the same function for existing tenants, so there is a single source.
Rules the database enforces
These hold even if a bug or a future code path skips JournalPostingService:
- Balanced. A deferred constraint trigger checks, at commit, that every posted entry has at least two lines, debits = credits, and the sums match the header totals.
- Immutable once posted. Lines of a non-draft entry cannot be inserted, changed or deleted. A posted header can only move
Posted → Reversed. Corrections are always new entries. - One live entry per source. A partial unique index on
(tenant, source_type, source_id)for liveORIGINALentries makes posting idempotent, so a retried event finds the existing entry.
Only app.bypass_rls = 'on' (platform maintenance, test teardown) lifts the immutability triggers.
Lifecycle
Draft → Posted → Reversed, or Draft → Cancelled (void). DocumentFlow holds the same graph as DocType.JOURNAL_ENTRY.
- Numbering.
JE-000001is drawn fromdocument_sequencewhen an entry is posted, so voided drafts leave no gap. - Separation of duties. With
require_separate_posteron (the default), the user who drafted an entry cannot post it. - Period control. Posting needs the entry's month to be open. Closing a month is refused while drafts are dated in it.
- Reversal. Posts a mirror-image entry dated today, or the original's date if that is later, then marks the original
Reversed.
Where entries come from
| Source | When | How it posts |
|---|---|---|
| Payroll run | Run marked Processed | Draft, for an accountant to review and post. Built by PayrollRunPostingBuilder from the same PayrollJournalAssembler the Payroll Journal report uses, mapped through GlAccountService. The report and the entry therefore always agree, which PayrollAccountingIT checks line by line. |
| Payroll run reversed | PayrollServiceImpl.reverse | Draft voided, or posted entry reversed. |
| Sales invoice | Issued / cancelled | Dr AR (face), Cr Sales revenue (net), Cr Output VAT. Cancel reverses. |
| Customer payment | Posted | Dr Cash (method Cash) or Bank, Cr AR. |
| Supplier invoice | Posted / cancelled | Dr Purchases (net), Dr Input VAT, Cr AP (amountDue() = total − EWT), Cr EWT payable. |
| Supplier payment | Posted | Dr AP, Cr Cash or Bank. |
| Manual | User | Draft, editable until posted. |
| Opening balances | User, once | Draft at the go-live date (see below). |
The two flows differ on purpose:
- Payroll posts after its transaction commits, in a new transaction (
PayrollAccountingListener). The ledger can never block or roll back a payroll. If drafting fails, the failure is logged and the run page offers Draft journal entry. - Commercial documents post in their own transaction (
CommerceAccountingListener). If the entry cannot be written, the invoice does not change either, so AR/AP never drift from the GL. One consequence: a document cannot be issued or posted with a date in a closed period.
Opening balances
Nothing is back-posted. Documents from before the ledger have no entries, so Accounting Settings → Opening balances drafts one entry:
- AR per customer for issued invoices with no entry, less posted receipts with no entry.
- AP per supplier the same way.
- The difference goes to Opening balance equity.
Cash, bank and payroll liabilities are added to that draft by hand before it is posted.
Reports
All reports are read from Posted and Reversed entries (a reversal is its own posted entry):
- Trial balance as of a date.
- General ledger: one account, with opening and running balance.
- Income statement for a range.
- Balance sheet as of a date. Earnings are computed because no closing entries exist yet.
- AR / AP aging: open documents bucketed by days past due, shown next to the control account balance. A difference usually means pre-ledger history still waiting for the opening entry.
Report queries are JPQL, so Hibernate's tenant filter applies to every aggregate.
On the enterprise grid
Chart of Accounts, Trial Balance, General Ledger, Financial Statements and Aging use the same
useEnterpriseGrid table as Employees (search, View and Table menus, saved views, tabs with
counts). Sorting and filtering run on the server:
- Chart of Accounts:
GET /api/accounting/accounts/searchis a JPA Specification onaccount. - The reports:
GET /api/accounting/reports/{trial-balance|general-ledger|statements|aging}/rows.- They are computed by
AccountingReportService, then filtered, sorted and paged byaccounting/grid/RowGrid. RowGriduses the same operators asCriteriaFilters, and sorting by an undeclared column returns 400.- Each page carries
totals(pinned under the grid, over the filtered rows) andmeta(balanced, control-account check, bucket totals).
- They are computed by
- Totals row:
ServerDataGridpinstotalswhenever a page includes them. Pages without totals are unaffected. - Downloads: the Table menu's Export CSV, Export PDF and Export Excel call
…/export?format=csv|pdf|xlsxwith the grid's own filters and sort.AccountingExportServicerenders them through the JasperTabularReportRenderer, with the company header, the active filters, column totals and the report's summary lines.
Permissions
| Permission | Grants |
|---|---|
accounting.view | Chart, journal, periods, settings (read) |
accounting.accounts.manage | Edit accounts and settings |
accounting.journal.create | Draft manual entries, void drafts, draft opening/payroll entries |
accounting.journal.post | Post and reverse |
accounting.periods.manage | Close and reopen periods |
accounting.reports.view | Trial balance, ledger, statements, aging |
The Accountant role holds all six plus read-only sales/purchasing invoices and payments and the payroll dashboard. It has no employee or payroll editing rights. System Administrator has all six. Payroll Administrator has accounting.view.
Adding a new posting source
- Write a
PostingSource<T>that returns aJournalDraft: date, memo, source type/id/ref, and lines fromControlAccountsorsystem_keyaccounts. - Add the source type to
JournalSourceTypeand tock_journal_entry_source_typein a migration. - Call
JournalPostingService.createDraftorcreateAndPostfrom a listener on the source module's event. Never writejournal_entryrows directly. - Add a builder unit test and an integration test that checks the entry against the source document's own totals.
Tests
JournalIntegrityIT: the database rules above, in raw SQL.JournalPostingServiceIT: the engine (idempotency, numbering, separation of duties, periods, reversal).PayrollAccountingIT: payroll → ledger reconciliation, reversal.CommerceAccountingIT: sales flow, closed periods, auto-post off.AccountingReportsIT: statements tie out, ledger running balance, aging vs. control, opening balance.AccountingTenantIsolationIT: both isolation layers.CommercePostingBuildersTestandjournalLines.test.ts: builders and the editor's balance check.e2e/Accounting/accounting-smoke.spec.ts: separation of duties and the pages, end to end.