Accounting Module — Architecture

A developer’s map of the Hitaji 360 accounting service. This document describes how the module is layered, how its ~40 controllers and services group by domain, how a write request travels from HTTP down to a balanced double-entry ledger posting, and where the multi-tenancy and period guards sit. All paths below are relative to hitaji-erp-api/src/accounting.

Purpose & scope

The accounting module is the single general-ledger authority for the whole platform. It owns the chart of accounts, the journal/ledger, invoices, bills, expenses, payments, budgets, contacts, financial reports — and, crucially, the bridge through which every other product (HR/payroll, SACCO, retail, fixed-assets, agri360, faith360, personal-finance) posts money into the ledger without touching the GL primitives directly. See posting-engine.md and accounting-bridge.md for the two deepest seams.

Layering

HTTP (controllers/*.controller.ts)
   │  @AdminOrJwtAuth + TenantAuthGuard + PermissionsGuard + @BusinessCtx
   ▼
Domain services (services/*.service.ts)
   │  business rules, DTO ⇄ entity, document lifecycle
   ▼
Posting engine (services/accounting-posting.service.ts + posting/*)
   │  validate → guard (period/frozen) → merge → round-off
   ▼
Ledger repository (repositories/accounting-ledger.repository.ts)
   │  one SERIALIZABLE transaction, idempotency, WHT balance deltas
   ▼
Ledger entities (entities/accounting-ledger-entry.entity.ts, journal-*.entity.ts)
   │  TypeORM → PostgreSQL
   ▼
PostgreSQL (single DB, tenant_id + workspace_id scoped)

A few cross-cutting layers wrap every write:

Auth/tenant: TenantAuthGuard (src/tenant/guards), the global PermissionsGuard (src/auth/permissions.guard.ts) keyed off @RequirePermissions(...), and the @BusinessCtx() decorator (src/common/business-context) which resolves the active businessId.
Idempotency: the @Idempotent() decorator (src/common/idempotency) on mutating bridge endpoints.
Events: EventEmitter2 — posting emits JOURNAL_POSTED_EVENT (events/journal-posted.event.ts); listeners live in listeners/.
Scheduling: @nestjs/schedule cron jobs (outbox drain, idempotency-key prune, overdue reminders, recurring transactions).

Module map

accounting.module.ts registers 39 controllers and a large provider list. The controllers/services group into the following domains.

General ledger core

Concern	Controller	Service(s)
Chart of accounts	`accounts.controller.ts`	`accounts.service.ts`, `account-defaults.service.ts`, `account-default-resolver.ts`, `account-invariants.service.ts`, `account-merge.service.ts`, `chart-template.service.ts`, `chart-import.service.ts`
Journals	`journal.controller.ts`	`journal.service.ts`, `journal-entry-template.service.ts`
Ledger posting engine	(none — internal)	`accounting-posting.service.ts` + `posting/*`
Opening balances	`opening-balances.controller.ts`	`opening-balances.service.ts`
Categories / cost centers	`categories.controller.ts`, `cost-centers.controller.ts`	`categories.service.ts`, `cost-centers.service.ts`, `org-unit-cost-center-sync.service.ts`

Receivables / payables (sub-ledger documents)

Concern	Controller	Service(s)
Invoices	`invoices.controller.ts`	`invoices.service.ts`, `invoice-returns.service.ts`, `invoice-overdue.service.ts`
Bills	`bills.controller.ts`	`bills.service.ts`, `bill-returns.service.ts`
Quotations	`quotations.controller.ts`	`quotations.service.ts`, `quotation-conversion.service.ts`, `quotation-expiry.service.ts`
Expenses	`expenses.controller.ts`, `expense-claim-types.controller.ts`	`expenses.service.ts`, `expense-claim-type.service.ts`
Payments & allocation	`payments.controller.ts`, `payment-reconciliation.controller.ts`, `payment-term.controller.ts`	`payments.service.ts`, `payment-reconciliation.service.ts`, `payment-deduction.service.ts`, `payment-receivable-resolver.ts`, `payment-schedule.service.ts`, `payment-term.service.ts`
Debts (AR) & reminders	`debts.controller.ts`, `debt-settings.controller.ts`, `reminder-settings.controller.ts`	`debt-settings.service.ts`, `overdue-reminder.*`, `reminder-settings.service.ts`
Contacts	`contacts.controller.ts`	`contacts.service.ts`, `contact-linking.service.ts`, `contact-balance.service.ts`

Cash, bank, petty cash

Concern	Controller	Service(s)
Bank reconciliation	`bank-reconciliations.controller.ts`, `bank-statement-lines.controller.ts`	`bank-reconciliations.service.ts`
Bank loans	`bank-loans.controller.ts`	`bank-loans.service.ts`
Petty cash	`petty-cash.controller.ts`	`petty-cash.service.ts`

Periods, close, tax

Concern	Controller	Service(s)
Periods & locking	`accounting-periods.controller.ts`, `period-reopen.controller.ts`	`period-close.service.ts`, `period-reopen.service.ts`, `period-summary.service.ts`
Year-end close	`year-end-close.controller.ts`	`year-end-close.service.ts`
Tax / WHT codes	`tax-code.controller.ts`, `withholding-code.controller.ts`	`tax-code.service.ts`, `withholding-code.service.ts` + `posting/vat-engine.ts`, `posting/wht-engine.ts`

Reporting & budgets

Concern	Controller	Service(s)
Financial reports	`financial-reports.controller.ts`, `report-presets.controller.ts`	`financial-reports.service.ts`, `report-presets.service.ts` (see `docs/accounting-reports.md`)
Budgets	`budgets.controller.ts`	`budgets.service.ts`, `budget-balance.service.ts`, `consolidated-budget.service.ts`
Recurring	`recurring-transactions.controller.ts`	`recurring-transactions.service.ts`, `recurring-transactions-scheduler.service.ts`

Integration surface (the bridge)

Concern	Controller	Service(s)
Product → GL bridge	`accounting-bridge.controller.ts`, `integration.controller.ts`	`accounting-bridge.service.ts`, `accounting-routing.service.ts`, `posting-profile-resolver.service.ts`, `bulk-posting.service.ts`, `accounting-outbox-writer.service.ts`, `accounting-intent-processor.service.ts`, `staff-posting-book-resolver.service.ts`, `employee-contact-provisioning.service.ts`, `integration.service.ts`

Settings, audit, documents

workspace-settings.controller.ts, print-settings.controller.ts, terms-templates.controller.ts, accounting-audit.controller.ts over print-settings.service.ts, terms-templates.service.ts, accounting-audit.service.ts, document-sequence.service.ts, document-template.service.ts, document-pdf.service.ts, pdf-render.service.ts.

How a write becomes a ledger posting

There are two front doors that converge on the same posting engine.

Front door A — a user posts a manual journal

JournalService.post() (services/journal.service.ts:324) re-checks balance, calls PeriodCloseService.assertPostingAllowed(), transitions the workflow state, flips the entry to POSTED, then calls the private postWithCurrentPipeline() (journal.service.ts:718) which builds an AccountingPostingContext (resolving businessId via AccountingRoutingService.resolveBusinessIdForWorkspace) and hands off to AccountingPostingService.postJournalEntryWithContext().

Front door B — another product posts through the bridge

product module → POST /accounting/bridge/journal-intents
   → AccountingBridgeService.publishJournalIntent
      → routing.resolve(businessId → book → workspaceId)
      → profileResolver.resolveJournalLines(systemCode → accountId)
      → journalService.create(...) → journalService.post(...)  ← rejoins front door A

Either way, control reaches AccountingPostingService, the single posting engine. It (accounting-posting.service.ts:198 validateAndPrepareRows):

Loads the referenced accounts (tenant + workspace scoped; throws if any account is out of scope — loadAccounts).
Runs PostingValidatorService.validate() — balance check (|Dr−Cr| ≤ 0.005), no line with both debit and credit, accounts postable/active.
Runs FrozenAccountGuardService.check() and PeriodLockGuardService.check().
Optionally merges duplicate rows (PostingRowMergerService) and appends a round-off row (RoundOffCalculatorService).
If any issue is collected, throws BadRequestException with code: 'POSTING_FAILED'; otherwise writes via AccountingLedgerRepository.createEntriesForJournalEntry(), which performs the insert inside a single transaction with a ledger-existence guard and (when supplied) applies WHT balance deltas in the same transaction.

The full engine internals — idempotency keys, the intent→outbox→ledger pipeline, posting profiles, and bulk posting — are documented in posting-engine.md.

Where multi-tenancy and period guards sit

Tenant isolation is enforced at every layer, not just the edge. The JWT yields a tenantId (extracted in src/tenant); domain services thread it into every repository call; the ledger repository scopes every query by tenant_id + workspace_id; and AccountingPostingService.loadAccounts() hard-fails if a journal line references an account outside the active tenant/workspace.
Business scoping: an accounting workspaceId is an accounting book id, not a task-management workspace (see the repo CLAUDE.md). The @BusinessCtx() decorator resolves the active businessId; AccountingRoutingService maps businessId → book → workspaceId and refuses to guess when a business has multiple active books with no default (BOOK_ROUTING_AMBIGUOUS).
Period locking is centralised in two places that agree on stable codes:
- PeriodCloseService.assertPostingAllowed() throws the typed PeriodClosedException with code: 'PERIOD_CLOSED' | 'PERIOD_LOCKED'. Called by JournalService.post/reverse/submitForApproval. Downstream products (the SACCO bridge) pattern-match on body.code — do not replace it with a generic throw.
- PeriodLockGuardService.check() (posting/period-lock-guard.service.ts) is the engine-level guard inside validateAndPrepareRows. It returns ok | override | blocked and is overridable via context.overrides.periodLock (the post-to-closed-period role).

Extension points

New product posting source → do not add a controller. Publish a journal intent through AccountingBridgeService and register a JournalSourceType mapping (accounting-bridge.service.ts mapIntentToSourceType). See accounting-bridge.md.
New account-mapping rule → add an AccountingPostingProfile (entities/accounting-posting-profile.entity.ts) keyed by (book, productKey, transactionType), resolved by PostingProfileResolver.
New financial report → extend financial-reports.service.ts; read docs/accounting-reports.md first (reconciliation contracts, snapshot hooks).
New posting-time validation/guard → add a service under posting/ and wire it into AccountingPostingService.validateAndPrepareRows so it runs for both front doors.
New entity column → ship a TypeORM migration (migrations/); synchronize: false in every environment, including local dev.

Overview

Getting Started

Basics

Master Data

Transactions

Periods & Compliance

Reports

Budgeting

Settings

Developer Guide

Accounting Module — Architecture

Purpose & scope

Layering

Module map

General ledger core

Receivables / payables (sub-ledger documents)

Cash, bank, petty cash

Periods, close, tax

Reporting & budgets

Integration surface (the bridge)

Settings, audit, documents

How a write becomes a ledger posting

Front door A — a user posts a manual journal

Front door B — another product posts through the bridge

Where multi-tenancy and period guards sit

Extension points

​Purpose & scope

​Layering

​Module map

​General ledger core

​Receivables / payables (sub-ledger documents)

​Cash, bank, petty cash

​Periods, close, tax

​Reporting & budgets

​Integration surface (the bridge)

​Settings, audit, documents

​How a write becomes a ledger posting

​Front door A — a user posts a manual journal

​Front door B — another product posts through the bridge

​Where multi-tenancy and period guards sit

​Extension points

Purpose & scope

Layering

Module map

General ledger core

Receivables / payables (sub-ledger documents)

Cash, bank, petty cash

Periods, close, tax

Reporting & budgets

Integration surface (the bridge)

Settings, audit, documents

How a write becomes a ledger posting

Front door A — a user posts a manual journal

Front door B — another product posts through the bridge

Where multi-tenancy and period guards sit

Extension points