Chart of accounts and GL configuration

ID	MOD-140
System	SD01
Repo	bank-core
Build status	Deployed
Deployed	Yes
Last commit	2b41724

---

Purpose

Provides a governed interface for defining, maintaining, and amending the institution's chart of accounts and GL account code configuration. Every posting in MOD-001 is validated against account codes defined here. The module enforces four-eyes approval for all changes, propagates activated accounts to downstream reporting modules automatically, and validates regulatory mappings before activation.

Context

Every bank operates a bespoke chart of accounts shaped by its management reporting preferences, regulatory obligations, and product portfolio. Without a governed chart of accounts interface, adding or amending GL account codes requires a developer deployment — introducing delay, risk of error, and an unaudited change path.

The platform ships with a default chart of accounts pre-mapped to RBNZ BS2A and APRA ARS 720 classifications. This default chart is sufficient to satisfy regulatory reporting requirements without customisation and cannot be deleted — system accounts are flagged is_system_account = true and are immutable to back-office staff. Banks extend the default chart by adding their own account codes for management reporting, cost centre allocation, or product-level tracking.

Regulatory mapping is validated before activation: any account code referenced in an RBNZ or APRA return must carry a valid mapping to the relevant regulatory line item taxonomy. Accounts mapped to a retired or renamed regulatory line item are flagged for review and cannot be activated until the mapping is corrected.

Account type hierarchy

The chart of accounts follows the standard five-type hierarchy used across banking:

Account type	Sub-type examples (banking)
Asset	Cash and cash equivalents, loans and advances, investment securities, deferred tax asset
Liability	Customer deposits, wholesale funding, accrued interest payable, deferred income
Equity	Share capital, retained earnings, other comprehensive income reserves
Income	Interest income (lending), fee income, trading income, other operating income
Expense	Interest expense (deposits, wholesale), credit impairment charge, staff costs, technology costs, regulatory levies

Sub-types are free-text strings that enable grouping within management reporting and are not validated against a fixed taxonomy. Account type is validated against the five permitted values at activation.

Regulatory mapping

Each GL account can carry one or more regulatory_mappings entries — JSON objects identifying the regulatory return, the line item code within that return, and the jurisdiction. Before an account is activated, every mapping is validated against the platform's regulatory line item taxonomy:

• If the line item code exists in the taxonomy and is live, the mapping is valid.
• If the line item code has been retired or renamed, the account is held in pending_review status and cannot be activated until the mapping is corrected.
• If no mapping is present and the account type implies regulatory reporting relevance (income, expense, certain asset and liability sub-types), a warning is surfaced to the approver — the approval is not blocked, but the proposer must acknowledge the absence of mapping.

The platform ships with regulatory line item taxonomies for RBNZ BS2A, RBNZ BS6, APRA ARS 720.0, and APRA ARS 740.0. These are updated by platform deployments when regulators amend their return templates.

Data model

-- core.gl_accounts
CREATE TABLE core.gl_accounts (
  account_code          TEXT PRIMARY KEY,
  account_name          TEXT NOT NULL,
  account_type          TEXT NOT NULL CHECK (account_type IN ('asset','liability','equity','income','expense')),
  account_subtype       TEXT,
  currency              TEXT NOT NULL DEFAULT 'NZD',
  is_system_account     BOOL NOT NULL DEFAULT false,
  regulatory_mappings   JSONB,           -- [{return, line_item_code, jurisdiction}]
  status                TEXT NOT NULL DEFAULT 'active'
                        CHECK (status IN ('active','inactive','pending_review')),
  parent_account_code   TEXT REFERENCES core.gl_accounts(account_code),
  created_at            TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- core.gl_account_proposals
CREATE TABLE core.gl_account_proposals (
  proposal_id       UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  account_code      TEXT NOT NULL,
  account_name      TEXT NOT NULL,
  account_type      TEXT NOT NULL,
  account_subtype   TEXT,
  currency          TEXT NOT NULL DEFAULT 'NZD',
  regulatory_mappings JSONB,
  parent_account_code TEXT,
  change_type       TEXT NOT NULL CHECK (change_type IN ('create','modify','deactivate')),
  change_reason     TEXT NOT NULL,
  proposed_by       UUID NOT NULL,
  proposed_at       TIMESTAMPTZ NOT NULL DEFAULT now(),
  status            TEXT NOT NULL DEFAULT 'pending'
                    CHECK (status IN ('pending','approved','rejected','live')),
  reviewed_by       UUID,               -- must differ from proposed_by
  reviewed_at       TIMESTAMPTZ,
  review_comment    TEXT,
  effective_date    DATE NOT NULL,
  applied_at        TIMESTAMPTZ,
  CONSTRAINT no_self_approval CHECK (proposed_by != reviewed_by)
);

System accounts (is_system_account = true) do not accept proposals from the back-office panel — any attempt to submit a proposal against a system account is rejected at the application layer with a structured error.

Maker/checker workflow

The chart of accounts change workflow follows the same maker/checker pattern as MOD-127 (product configuration panel):

1. Propose. A finance or product analyst submits a proposal: new account code, modification to an existing account's name, sub-type or regulatory mapping, or deactivation of an unused account. The system validates the regulatory mappings at submission time and flags any issues for resolution before the proposal is submitted for review.

2. Review. A second authorised staff member — who cannot be the proposer — reviews the proposal. They may approve, reject, or return for revision. Approval requires the reviewer to acknowledge any regulatory mapping warnings.

3. Activate. On the effective date, approved proposals are applied: the core.gl_accounts table is updated, the change is logged to MOD-047 with full before/after state, and the updated chart is propagated to MOD-080 and any registered downstream reporting modules within 60 seconds.

4. Deactivated accounts. Deactivated accounts (status = inactive) remain in the table and are queryable for historical reporting. They cannot be selected as the target of new postings in MOD-001. Reactivation requires a new proposal.

Key operations

Add account. Submit a proposal for a new account code with type, sub-type, optional parent, currency, and regulatory mappings. Regulatory mapping validation runs at proposal submission. Four-eyes approval required before activation.

Modify account. Submit a proposal to change the name, sub-type, or regulatory mappings of an existing non-system account. The current values are captured in the proposal as before state for the audit log.

Deactivate account. Submit a deactivation proposal. The system checks whether the account has any live posting rules in MOD-001 or live regulatory mappings in MOD-080 that would be broken by deactivation — if so, a warning is surfaced. Deactivation does not delete historical data.

Regulatory mapping update. Regulatory mapping changes follow the same proposal workflow. A mapping change on an account used in regulatory returns is treated as a REP-004 GATE event and requires the regulatory mapping validation to pass before approval is permitted.

Requirements

FR-621 — Posting validation: every posting in MOD-001 must validate both the debit and credit leg account codes against core.gl_accounts with status active; postings referencing unknown or inactive GL codes must be rejected with a structured error identifying the invalid code.

FR-622 — System account immutability: system accounts flagged is_system_account = true must not be modifiable via the back-office proposal workflow; all chart of accounts changes must enforce four-eyes approval with the proposed_by != reviewed_by constraint at the database level.

FR-623 — Downstream propagation: activated GL account changes must be propagated to MOD-080 (statutory reporting) and registered downstream reporting modules within 60 seconds of activation; deprecated accounts must remain queryable for historical reporting but must not be selectable for new postings.

FR-624 — Regulatory mapping validation: each GL account's regulatory_mappings must be validated against the known regulatory line item taxonomy before activation; accounts mapped to retired or renamed line items must be flagged for review; the platform must ship with a default chart pre-mapped to RBNZ BS2A and APRA ARS 720 classifications.

---

Module dependencies

Depends on

Module	Title	Required?	Contract	Reason
MOD-001	Double-entry posting engine	Required	—	The posting engine references GL account codes from this module's chart when validating posting rules; unknown or inactive account codes must be rejected at the point of posting.
MOD-080	Statutory financial reporting & ERP integration	Required	—	Statutory reporting maps regulatory line items to GL account codes maintained here; changes to the chart must be propagated to report templates within 60 seconds of activation.
MOD-047	Agent action logger	Required	—	All chart of accounts changes are logged to the agent action audit trail with full before/after state, satisfying GOV-006.
MOD-127	Product configuration panel	Optional	—	Product configuration changes that reference interest income or fee income GL codes are validated against the chart of accounts to prevent referencing inactive or non-existent codes.

Required by

Module	Title	As	Contract
MOD-118	Member equity and share registry	Hard dependency	—

---

Policies satisfied

Policy	Title	Mode	How
REP-004	Financial Statements Policy	GATE	Changes to GL account codes used in regulatory reporting must be reviewed and approved before taking effect; any code used in an RBNZ or APRA return must have a valid regulatory mapping before it can be activated.
GOV-006	Internal Audit Policy	LOG	All chart of accounts changes are logged immutably with the proposer, approver, timestamp, and before/after state, providing a complete audit trail for internal and regulatory review.
REP-002	Prudential Reporting Policy	AUTO	GL account definitions are automatically published to MOD-080 (statutory reporting) and MOD-082 (management reporting) when activated, ensuring report templates reference only current, active account codes.
GOV-007	Conflicts of Interest Policy	GATE	All chart of accounts changes require four-eyes (maker/checker) approval before taking effect; the proposer must not be the approver, enforced at the database constraint level.

---

Capabilities satisfied

(No capabilities mapped)

---

Part of SD01 — Core Banking Platform Compiled 2026-05-22 from source/entities/modules/MOD-140.yaml