Accounting Engine Design
Use When
- An approved SRS contains sales, payments, inventory, payroll, tax, assets or reporting that must post to a ledger.
Do Not Use When
- Do not use to invent accounting policy, tax treatment, chart mappings or IFRS conclusions; obtain finance-doctrine and authorised accountant evidence.
Required Inputs
| Artefact |
Source or provider |
Required? |
Missing behaviour |
| Approved finance requirements and finance-doctrine decisions |
SRS and canonical finance engine |
Required |
Stop if posting rules, reporting basis or statutory treatment are unresolved. |
| HLD, source events, tenancy and period controls |
Architecture, domain and finance owners |
Required |
Return a design-gap register when event or control ownership is missing. |
Workflow
- Read the named inputs and confirm their approval, version and unresolved decisions.
- Apply the decision rules below before drafting; stop on a missing authority, unsafe assumption or unresolved scope driver.
- Produce the Accounting Engine Design and finance quality-gate evidence through the existing domain procedure and load only the references needed for the chosen branch.
- Trace each material statement in the Accounting Engine Design and finance quality-gate evidence to an input, decision or explicitly qualified assumption.
- Verify the observable acceptance conditions, record unassessed checks, and hand the artefacts to their named consumers.
- If validation fails, recover by correcting the source decision or artefact and rerun the affected check; do not weaken the acceptance condition.
Outputs
| Artefact |
Consumer |
Observable acceptance condition |
| Accounting Engine Design and finance quality-gate evidence |
Finance, backend, data, audit, test and operations teams |
Every source event maps through one posting service to balanced immutable journals; idempotency, reversal, period, rebuild, tenancy and audit tests are specified. |
Evidence Produced
| Evidence |
Consumer |
Acceptance condition |
| Source and decision trace |
Reviewer and downstream owner |
Each material statement cites an approved input, named decision or qualified open issue. |
| Completed verification record |
Release or phase gate owner |
Every applicable check records pass/fail; unavailable checks remain not assessed. |
Capability and permission boundaries
Read-only is the default for analysis, review, evaluation and planning. Read and search access to authorised project artefacts are required. Editing is limited to an explicitly requested project deliverable. Execution may run document, syntax or validation checks. Network access is used only for facts that require current verification. Do not publish, spend, change production, approve policy, or claim certification without explicit authority.
Degraded mode
If any required capability is unavailable, return the narrowest useful qualified Accounting Engine Design and finance quality-gate evidence draft plus a gap register showing the missing item, affected sections, risk and owner. Never convert an unassessed check into a pass.
Decision Rules
| Choice |
Action |
Failure or risk avoided |
| Financial event is approved and postable |
Create balanced journal through LedgerPostingService |
Subledgers cannot bypass controls |
| Period is closed or event is duplicate |
Reject or route authorised reversal/adjustment |
Ledger history remains immutable |
Quality Standards
- Preserve repository terminology and trace every material choice to project context.
- Use deterministic acceptance conditions; replace vague quality claims with an observable check, threshold or named approval.
- Cover error, empty, edge, recovery and operational cases relevant to this skill.
- Verify standards, citations, APIs and package names before relying on them; qualify what cannot be checked.
- Stop release for a failed safety, security, legal, financial, accessibility or data-integrity gate.
Anti-Patterns
- Writing directly from sales tables to ledger tables. Fix: use the posting service and mapping rules.
- Updating a posted journal. Fix: create an authorised reversal and replacement.
- Storing a balance with no rebuild path. Fix: derive and reconcile it from journal lines.
- Omitting idempotency on event consumption. Fix: enforce a source-event key.
- Inventing debit/credit mappings. Fix: require finance-doctrine approval and traceable configuration.
References
Use When
- The approved SRS includes money-handling or embedded accounting requirements.
- A design document must specify the accounting write path, schema, services, reports, and invariants.
Hard Rules
- NEVER design a direct write path from sales, inventory, payroll, payments, or assets into ledger tables.
- NEVER design mutable posted journals.
- MUST show how materialized balances rebuild from journal lines.
- MUST include
tenant_id on accounting tables unless explicitly single-tenant.
Canonical Data Model
Required tables:
chart_of_accountsaccount_mappingsposting_rule_versionsjournal_entriesjournal_linesaccounting_periodsaccounting_integrity_runsaccounting_audit_log
Recommended supporting tables:
tax_ratesexchange_ratesinventory_cost_layersfixed_assetspayroll_runsbank_accountsfunds for NGOs and donor-funded projects
LedgerPostingService Interface
interface LedgerPostingService
{
public function post(JournalEntry $entry): PostedJournal;
}
The design shall document validations for debit-credit equality, tenant scope, open period, active accounts, idempotency key, source document state, mapping completeness, currency policy, and database transaction boundaries.
Design Sections To Produce
- Accounting context and standard profile.
- Service boundaries and event producers.
- Account resolver and mapping tables.
- Posting service contract.
- Database schema and constraints.
- Reversal and correction workflow.
- Period close and lock workflow.
- Subledger and control-account reconciliation.
- Report projection and cache rebuild strategy.
- Audit trail and tamper-evidence strategy.
- Operational jobs: nightly integrity, report rebuild, FX revaluation, depreciation, payroll remittance checks.
Outputs
- SDS/HLD/LLD accounting-engine section.
- ERD/table specification.
- Service interface and sequence diagram text.
- Reconciliation and report rebuild design.
1---2name: 16-accounting-engine-design3description: Use when approved money-flow requirements need SDS/HLD/LLD for an embedded accounting engine with append-only journals, posting service, periods, reversals, idempotency, subledgers, rebuilds and audit trail; consult the finance doctrine and use database-design for general persistence.4---5# Accounting Engine Design6<!-- dual-compat-start -->7## Use When89- An approved SRS contains sales, payments, inventory, payroll, tax, assets or reporting that must post to a ledger.1011## Do Not Use When1213- Do not use to invent accounting policy, tax treatment, chart mappings or IFRS conclusions; obtain finance-doctrine and authorised accountant evidence.1415## Required Inputs1617| Artefact | Source or provider | Required? | Missing behaviour |18|---|---|---|---|19| Approved finance requirements and finance-doctrine decisions | SRS and canonical finance engine | Required | Stop if posting rules, reporting basis or statutory treatment are unresolved. |20| HLD, source events, tenancy and period controls | Architecture, domain and finance owners | Required | Return a design-gap register when event or control ownership is missing. |2122## Workflow23241. Read the named inputs and confirm their approval, version and unresolved decisions.252. Apply the decision rules below before drafting; stop on a missing authority, unsafe assumption or unresolved scope driver.263. Produce the Accounting Engine Design and finance quality-gate evidence through the existing domain procedure and load only the references needed for the chosen branch.274. Trace each material statement in the Accounting Engine Design and finance quality-gate evidence to an input, decision or explicitly qualified assumption.285. Verify the observable acceptance conditions, record unassessed checks, and hand the artefacts to their named consumers.296. If validation fails, recover by correcting the source decision or artefact and rerun the affected check; do not weaken the acceptance condition.3031## Outputs3233| Artefact | Consumer | Observable acceptance condition |34|---|---|---|35| Accounting Engine Design and finance quality-gate evidence | Finance, backend, data, audit, test and operations teams | Every source event maps through one posting service to balanced immutable journals; idempotency, reversal, period, rebuild, tenancy and audit tests are specified. |3637## Evidence Produced3839| Evidence | Consumer | Acceptance condition |40|---|---|---|41| Source and decision trace | Reviewer and downstream owner | Each material statement cites an approved input, named decision or qualified open issue. |42| Completed verification record | Release or phase gate owner | Every applicable check records pass/fail; unavailable checks remain `not assessed`. |4344## Capability and permission boundaries4546Read-only is the default for analysis, review, evaluation and planning. Read and search access to authorised project artefacts are required. Editing is limited to an explicitly requested project deliverable. Execution may run document, syntax or validation checks. Network access is used only for facts that require current verification. Do not publish, spend, change production, approve policy, or claim certification without explicit authority.4748## Degraded mode4950If any required capability is unavailable, return the narrowest useful qualified Accounting Engine Design and finance quality-gate evidence draft plus a gap register showing the missing item, affected sections, risk and owner. Never convert an unassessed check into a pass.5152## Decision Rules5354| Choice | Action | Failure or risk avoided |55|---|---|---|56| Financial event is approved and postable | Create balanced journal through LedgerPostingService | Subledgers cannot bypass controls |57| Period is closed or event is duplicate | Reject or route authorised reversal/adjustment | Ledger history remains immutable |5859## Quality Standards6061- Preserve repository terminology and trace every material choice to project context.62- Use deterministic acceptance conditions; replace vague quality claims with an observable check, threshold or named approval.63- Cover error, empty, edge, recovery and operational cases relevant to this skill.64- Verify standards, citations, APIs and package names before relying on them; qualify what cannot be checked.65- Stop release for a failed safety, security, legal, financial, accessibility or data-integrity gate.6667## Anti-Patterns6869- Writing directly from sales tables to ledger tables. Fix: use the posting service and mapping rules.70- Updating a posted journal. Fix: create an authorised reversal and replacement.71- Storing a balance with no rebuild path. Fix: derive and reconcile it from journal lines.72- Omitting idempotency on event consumption. Fix: enforce a source-event key.73- Inventing debit/credit mappings. Fix: require finance-doctrine approval and traceable configuration.7475## References7677- [Database Design neighbour](../04-database-design/SKILL.md)78- [Finance engine router](../../AGENTS.md#finance--accounting-trigger)79<!-- dual-compat-end -->8081828384## Use When8586- The approved SRS includes money-handling or embedded accounting requirements.87- A design document must specify the accounting write path, schema, services, reports, and invariants.8889## Hard Rules9091- NEVER design a direct write path from sales, inventory, payroll, payments, or assets into ledger tables.92- NEVER design mutable posted journals.93- MUST show how materialized balances rebuild from journal lines.94- MUST include `tenant_id` on accounting tables unless explicitly single-tenant.9596## Canonical Data Model9798Required tables:99100- `chart_of_accounts`101- `account_mappings`102- `posting_rule_versions`103- `journal_entries`104- `journal_lines`105- `accounting_periods`106- `accounting_integrity_runs`107- `accounting_audit_log`108109Recommended supporting tables:110111- `tax_rates`112- `exchange_rates`113- `inventory_cost_layers`114- `fixed_assets`115- `payroll_runs`116- `bank_accounts`117- `funds` for NGOs and donor-funded projects118119## LedgerPostingService Interface120121```php122interface LedgerPostingService123{124 public function post(JournalEntry $entry): PostedJournal;125}126```127128The design shall document validations for debit-credit equality, tenant scope, open period, active accounts, idempotency key, source document state, mapping completeness, currency policy, and database transaction boundaries.129130## Design Sections To Produce1311321. Accounting context and standard profile.1332. Service boundaries and event producers.1343. Account resolver and mapping tables.1354. Posting service contract.1365. Database schema and constraints.1376. Reversal and correction workflow.1387. Period close and lock workflow.1398. Subledger and control-account reconciliation.1409. Report projection and cache rebuild strategy.14110. Audit trail and tamper-evidence strategy.14211. Operational jobs: nightly integrity, report rebuild, FX revaluation, depreciation, payroll remittance checks.143144## Outputs145146- SDS/HLD/LLD accounting-engine section.147- ERD/table specification.148- Service interface and sequence diagram text.149- Reconciliation and report rebuild design.
peterbamuhigire