Skip to main content

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.yaml for what is and is not covered.

Data model (V128–V130)​

TablePurpose
accountChart 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_periodCalendar months, created the first time something posts into them. OPEN / CLOSED.
accounting_settingsOne row per tenant: the control accounts commercial documents use, plus commerce_auto_post, require_separate_poster and go_live_date.
journal_entry / journal_entry_lineEntries 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 live ORIGINAL entries 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-000001 is drawn from document_sequence when an entry is posted, so voided drafts leave no gap.
  • Separation of duties. With require_separate_poster on (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​

SourceWhenHow it posts
Payroll runRun marked ProcessedDraft, 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 reversedPayrollServiceImpl.reverseDraft voided, or posted entry reversed.
Sales invoiceIssued / cancelledDr AR (face), Cr Sales revenue (net), Cr Output VAT. Cancel reverses.
Customer paymentPostedDr Cash (method Cash) or Bank, Cr AR.
Supplier invoicePosted / cancelledDr Purchases (net), Dr Input VAT, Cr AP (amountDue() = total − EWT), Cr EWT payable.
Supplier paymentPostedDr AP, Cr Cash or Bank.
ManualUserDraft, editable until posted.
Opening balancesUser, onceDraft 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/search is a JPA Specification on account.
  • The reports: GET /api/accounting/reports/{trial-balance|general-ledger|statements|aging}/rows.
    • They are computed by AccountingReportService, then filtered, sorted and paged by accounting/grid/RowGrid.
    • RowGrid uses the same operators as CriteriaFilters, and sorting by an undeclared column returns 400.
    • Each page carries totals (pinned under the grid, over the filtered rows) and meta (balanced, control-account check, bucket totals).
  • Totals row: ServerDataGrid pins totals whenever 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|xlsx with the grid's own filters and sort. AccountingExportService renders them through the Jasper TabularReportRenderer, with the company header, the active filters, column totals and the report's summary lines.

Permissions​

PermissionGrants
accounting.viewChart, journal, periods, settings (read)
accounting.accounts.manageEdit accounts and settings
accounting.journal.createDraft manual entries, void drafts, draft opening/payroll entries
accounting.journal.postPost and reverse
accounting.periods.manageClose and reopen periods
accounting.reports.viewTrial 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​

  1. Write a PostingSource<T> that returns a JournalDraft: date, memo, source type/id/ref, and lines from ControlAccounts or system_key accounts.
  2. Add the source type to JournalSourceType and to ck_journal_entry_source_type in a migration.
  3. Call JournalPostingService.createDraft or createAndPost from a listener on the source module's event. Never write journal_entry rows directly.
  4. 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.
  • CommercePostingBuildersTest and journalLines.test.ts: builders and the editor's balance check.
  • e2e/Accounting/accounting-smoke.spec.ts: separation of duties and the pages, end to end.